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1 Tutorial 

This chapter gives a basic introduction to working with LilyPond. 

1.1 Compiling a file 

This section introduces “compiling”—the processing of LilyPond input files (written by you) to 
produce output files. 

1.1.1 Entering input 

“Compiling” is the term used for processing an input file in LilyPond format to produce output 
file(s). Output files are generally PDF (for printing or viewing), MIDI (for playing), and PNG 
(for online use). LilyPond input files are simple text files. 

This example shows a simple input file: 

\version "2.18.2" 

{ 

c 1 e ' g' e 1 

> 

The graphical output is: 



In addition, LilyPond input is case sensitive. ‘{ c d e }’ is valid input; ‘{ C D E }’ will produce 
an error message. 

Producing output 

The method of producing output depends on your operating system and the program(s) you 
use. 

• Section 1.1.2 [MacOS X], page 2 Section 1.1.2 [MacOS X], page 2 (graphical) 

• Section 1.1.3 [Windows], page 6 Section 1.1.3 [Windows], page 6 (graphical) 

• Section 1.1.4 [Command-line], page 11 Section 1.1.4 [Command-line], page 11 (command¬ 
line) 

There are several other text editors available with specific support for LilyPond. For more 
information, see Section “Easier editing” in General Information. 

( A 

Note: The first time you ever run LilyPond, it may take a minute or 
two because all of the system fonts have to be analyzed first. After this, 

LilyPond will be much faster! 

v_y 
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1.1.2 MacOS X 

f \ 

Note: These instructions assume that you are using the LilyPond appli¬ 
cation. If you are using any of the programs described in Section “Easier 
editing” in General Information, please consult the documentation for 
those programs if you have any problems. 

v_ 


Step 1. Create your ‘.ly’ file 

Double click the LilyPond.app, an example hie will open. 


W~ 

fteleprti to LilyPond 




Untitled 


Congratulations, LilyPond has been installed successfully. 

Now to take it for 1 the first test run. 

1. Save this file 

2 . Select 

> Typeset file 
from the menu, 

The file is processed, and 

3. The pop viewer will pop up. Click one of the notetvMds, 

That’s it. For more infarction,, visit http://Lilyp<ind.org . 
i.} 

\header-[ 

title - "A scale in Li.LyPond'' 

} 

\relative { 

cdefga.bc 

} 

\version "2.14.0" S necessary for upgrading to future LilyPond versions. 
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From the menus along the top left of your screen, select File > Save. 



Choose a name for your file, for example ‘test.ly’. 


r\ n 


Unilcled 


HI - 

t 


Save As igsi. ly 


Where Desktop 


Congrotul 
Nlm to tc 
1. 5iJVf 
Z. 5slect 

Gonplle > Typeset file 
the WiSw , 

The 5-C hhrl 




r 


Cancel Save rj 

-- y 
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Step 2. Compile (with LilyPad) 

From the same menus, select Compile > Typeset. 



A new window will open showing a progress log of the compilation of the file you have just 
saved. 


0 O O UlyPond — /Users/James/Desktop/testJy 

| Processing VUsers/jartes/D&sktop/tesfc.ly' 

Parsing.. . 

Interpreting music,,, 

Preprocessing graphical objects>, „ 

Solving l page-breaking chunks.... [1: 1 poges] 

Drawing systems... 

Layout output to 'test,ps'.,. 

Conwe r tirig to './tost.pdf'... 


A 


Stop 
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Step 3. View output 

Once the compilation has finished, a PDF file will be created with the same name as the original 
file and will be automatically opened in the default PDF viewer and displayed on your screen. 


Q test. lidf (i PlKJh) 

h- j (M i C H'-t MAM [gp f □ ( o 0 ( j5p. ") 

Fnrfebi h(M rum Z±am Tc ra tfofrc T&a Sctecc Markup Annonnc Crop 


A scale iu LilyPond 

f i-j jj iirJrf ] 


Other commands 

To create new files for LilyPond, begin by selecting File > New 
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or File > Open to open and edit existing files you have saved previously. 



You must save any new edits you make to your file before you Compile > Typeset and if the 
PDF file is not displayed check the window with the progress log for any errors. 


If you are not using the default Preview PDF viewer that comes with the Mac Operating 
system and you have the PDF file generated from a previous compilation open, then any further 
compilations may fail to generate an update PDF until you close the original. 


1.1.3 Windows 

( -\ 

Note: These instructions assume that you are using the built-in LilyPad 
editor. If you are using any of the programs described in Section “Easier 
editing” in General Information, please consult the documentation for 
those programs if you have any problems compiling a file, 
v_ J 
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Step 1. Create your ‘.ly’ file 

Double-click the LilyPond icon on your desktop and an example file will open. 


* Welcome_to_LilyPond.ly - LilyPad 


1 File Edit Search Help 





Welcome to LilyPond 


Congratulations, LilyPond has been installed successfully. 

Nora to take it for the first test run. 

1. Save this LilyPond file on your desktop with the name "test.ly". 

2. Pick it up from the desktop with your mouse pointer, drag and drop 
it onto the LilyPond icon. 

3. LilyPond automatically produces a PDF file from the musical scale 
belora. 

4. To print or view the result, click on the neraly produced file 
called 

test.pdf 

5. If you see a piece of music raith a scale, LilyPond is working 
properly. 

Next, you'll want to get started on your own scores. To do this you'll 
need to learn about using LilyPond. 

LilyPond's interface is text-based, rather than graphical. Please visit the 
help page at http://lilypond.org/introduction.html. This rail! 
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From the menus that appear along the top of the example file, select File > Save as. Do 
not use the File > Save for the example file as this will not work until you have given it a valid 
LilyPond file name. 


* Welcome_to_LilyPond.Iy - LilyPad 

File 


New 

Ctrl+N 

Open... 

Ctrl+O 

Save 

Ctrl+S 

1 Save as... 

Print 

Ctrl+P 

Page Setup... 

r 

Printer Setup... 


Exit 1 


2. Pick it up from the desktop with your mouse pointer, drag and drop 
it onto the LilyPond icon. 

3. LilyPond automatically produces a PDF file from the musical scale 
below. 

4. To print or view the result, click on the newly produced file 
called 

test.pdf 

5. If you see a piece of music with a scale, LilyPond is working 
properly. 

Next, you'll want to get started on your own scores. To do this you'll 
need to learn about using LilyPond. 

LilyPond's interface is text-based, rather than graphical. Please visit the 
help page at http://lilypond.org/introduction.html. This will 


Choose a name for your file, for example ‘test.ly’. 
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Step 2. Compile 

To turn your LilyPond file into a music score, you need to compile it. This can be done a number 
of ways - using drag and drop, with right-click, double-clicking or using the command line (a 
DOS box). We’ll look at the first three to start with. 

1. Drag-and-drop the file directly onto the LilyPond icon on the desktop. 



Not much will seem to happen, but after a short while, you should see two new files on your 
desktop - ‘test.log’ and ‘test.pdf’. 

2. Right-click on the file and from the pop-up context menu and choose Generate PDF. 



3. Or simply double-click the ‘test. ly’. 
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Step 3. View output 

‘test .pdf’ contains the engraved ‘test. ly’ file. Double-click it and it should open in your PDF 
viewer: 



Other commands 

To create a new file, begin by selecting File > New from within any previously created file or 
File > Open to open and edit any files you have saved before. You can also edit a file by 
right-clicking it and selecting Edit source. 
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You must save any edits you make before you try to compile your file. If the PDF file is not 
created or the output is not what you expected, check the log file that will have been created 
during the compilation attempt for any errors. 


B bad. log - Notepad 


File Edit Format View Help 


# -*-compi1atlon-*- 

Processing 'C:/Documents and Settings/Phil/Desktop/bad.1y' 

Parsing... 

C:/Documents and Settings/Phil/Desktop/bad.ly:9:1: error: syntax error, 
unexpected '/' 

/relative c' { 

Interpreting music... 
preprocessing graphical objects... 

Finding the ideal number of pages... 

Fitting music on l page_ 

Drawing systems... 

Layout output to '/Documents and Settings/Phil/Desktop/bad.ps’... 
converting to '/Documents and settings/Phil/Desktop/bad.pdf’... 
fatal error: failed files: "C:\\Documents and 
settings\\Phil\\Desktop\\bad.ly" 



This log file is overwritten each time you compile your LilyPond file. 

If you are viewing your file in a PDF viewer, then you must close the PDF if you wish to try 
a new compilation as it may fail to create the new PDF while it is still being viewed. 


B bad. log - Notepad 


File Edit Format View Help 
Jf -*-compi 1 ati on-*- 

Processing "C:/Oocuments and Settings/Phil/Desktop/bad.ly' 

Parsing... 

Interpreting music... 
preprocessing graphical objects... 

Finding the ideal number of pages... 

Fitting music on l page... 

Drawing systems... 

Layout output to '/Documents and settings/Phil/Desktop/bad.ps’... 
Converting to '/Documents and Settings/Phil/Desktop/bad.pdf'... 
warning: (95 -q -dNOSAFER -dDEVICEWIDTHPOINTS=595.28 - 

dDEVlCEHElGHTPOlNTS=84l.89 -dcompatibi1ityLevel=1.4 -dNOPAUSE -dBATCH - 
rl200 -sDEVICE=pdfwrite -sOutputFi1e=/Documents and 
settings/Phil/Desktop/bad.pdf -c.setpdfwrite -f/Documents and 
Setti ngs/Phi l/Desktop/bad.ps)' failed (l) 

fatal error: failed files: "C:\\Documents and 
settings\\Phil\\Desktop\\bad.ly" 



1.1.4 Command-line 


Note: These instructions assume that you are familiar with command¬ 
line programs. If you are using any of the programs described in Section 
“Easier editing” in General Information, please consult the documenta¬ 
tion for those programs if you have any problems compiling a file. 

v_ y 


Step 1. Create your ‘.ly’ file 

Create a text file called ‘test.ly’ and enter: 

\version "2.18.2" 

{ 

c 1 e ' g' e 1 

> 
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Step 2. Compile (with command-line) 

To process ‘test. ly’, type the following at the command prompt: 

lilypond test.ly 
You will see something resembling: 

GNU LilyPond 2.18.2 
Processing 'test.ly' 

Parsing... 

Interpreting music... 

Preprocessing graphical objects... 

Solving 1 page-breaking chunks...[1: 1 pages] 

Drawing systems... 

Layout output to 'test.ps 1 ... 

Converting to './test.pdf 1 ... 

Success: compilation successfully completed 

Step 3. View output 

You may view or print the resulting ‘test.pdf’. 

1.2 How to write input files 

This section introduces some basic LilyPond syntax to help get you started writing input files. 

1.2.1 Simple notation 

LilyPond will add some notation elements automatically. In the next example, we have only 
specified four pitches, but LilyPond has added a clef, time signature, and rhythms. 

{ 

c 1 e 1 g 1 e 1 

> 



This behavior may be altered, but in most cases these automatic values are useful. 

Pitches 

Music Glossary: Section “pitch” in Music Glossary, Section “interval” in Music Glossary, 
Section “scale” in Music Glossary, Section “middle C” in Music Glossary, Section “octave” 
in Music Glossary, Section “accidental” in Music Glossary. 

The easiest way to enter notes is by using \relative mode. In this mode, the octave is chosen 
automatically by assuming the following note is always to be placed closest to the previous note, 
i.e., it is to be placed in the octave which is within three staff spaces of the previous note. We 
begin by entering the most elementary piece of music, a scale, in which every note is within just 
one staff space of the previous note. 

7. set the starting point to middle C 
\relative c 1 { 
c d e f 
g a b c 

> 











Chapter 1: Tutorial 


13 



The initial note is middle C. Each successive note is placed closest to the previous note - 
in other words, the first c is the closest C to middle C. This is followed by the closest D to the 
previous note. We can create melodies which have larger intervals, still using only \relative 
mode: 

\relative c 1 { 
d f a g 
c b f d 

> 



It is not necessary for the first note of the melody to start on the note which specifies the starting 
pitch. In the previous example, the first note - the d - is the closest D to middle C. 

By adding (or removing) quotes 1 or commas , from the ‘\relative c ” command, we can 
change the starting octave: 

% one octave above middle C 
\relative c 11 { 
e c a c 

> 



Relative mode can be confusing initially, but is the easiest way to enter most melodies. Let 
us see how this relative calculation works in practice. Starting from a B, which is on the middle 
line in a treble clef, you can reach a C, D and E within 3 staff spaces going up, and an A, G 
and F within 3 staff spaces going down. So if the note following a B is a C, D or E it will be 
assumed to be above the B, and an A, G or F will be assumed to be below. 


\relative c 11 { 


b 

c 

l C 

is 

i 

staff 

space up 

', SO 

is the 

c above 

b 

d 

% d 

is 

2 

up 

or 

5 

down. 

so 

is 

the 

d 

above 

b 

e 

1 e 

is 

3 

up 

or 

4 

down. 

so 

is 

the 

e 

above 

b 

a 

l a 

is 

6 

up 

or 

1 

down. 

so 

is 

the 

a 

below 

b 

g 

% g 

is 

5 

up 

or 

2 

down. 

so 

is 

the 

g 

below 

b 

f 

7. f 

is 

4 

up 

or 

3 

down. 

so 

is 

the 

f 

below 


> 


/ ,, = 


0 _ 


p 



_ 


■ — 9 — 

Fz 

-m — 

•-J- 



— 






1-1-- 


Exactly the same happens even when any of these notes are sharpened or flattened. Acci¬ 
dentals are totally ignored in the calculation of relative position. Precisely the same staff space 
counting is done from a note at any other position on the staff. 

To add intervals that are larger than three staff spaces, we can raise the octave by adding a 
single quote 1 (or apostrophe) to the note name. We can lower the octave by adding a comma 
, to the note name. 
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\relative c 11 { 
a a, c 1 f , 
g g'' a,, f 1 

> 



To change a note by two (or more!) octaves, we use multiple 1 ' or , , - but be careful that you 
use two single quotes 1 1 and not one double quote " ! 

Durations (rhythms) 

Music Glossary: Section “beam” in Music Glossary, Section “duration” in Music Glossary, 
Section “whole note” in Music Glossary, Section “half note” in Music Glossary, Section “quarter 
note” in Music Glossary, Section “dotted note” in Music Glossary. 

The duration of a note is specified by a number after the note name: 1 for a whole note, 2 
for a half note, 4 for a quarter note and so on. Beams are added automatically. 

If you do not specify a duration, the previous duration is used for the next note. The duration 
of the first note defaults to a quarter note. 

\relative c 11 { 
al 

a2 a4 a8 a 

al6 a a a a32 a a a a64 aaaaaaaa2 

> 




To create dotted notes, add a dot . to the duration number. The duration of a dotted note 
must be stated explicitly (i.e., with a number). 

\relative c 11 { 
a4 a a4. a8 
a8. al6 a a8. a8 a4. 


p 

— 

— 

-IVt 

——Ft— K—1 — 

aL I •j n 

1) 

L) 

rfls l' m.m.a 

? m. 

i 

i 

i 

i 

i 

i 


> 
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Rests 

Music Glossary: Section “rest” in Music Glossary. 

A rest is entered just like a note with the name r : 

\relative c 11 { 
a4 r r2 

r8 a r4 r4. r8 

> 



Time signature 

Music Glossary: Section “time signature” in Music Glossary. 

The time signature can be set with the \time command: 

\relative c 11 { 

\time 3/4 
a4 a a 
\time 6/8 
a4. a 
\time 4/4 
a4 a a a 

> 



Tempo marks 

Music Glossary: Section “tempo indication” in Music Glossary , Section “metronome” in Music 
Glossary. 

The tempo indication and metronome mark can be set with the \tempo command: 

\relative c 11 { 

\time 3/4 
\tempo "Andante" 
a4 a a 
\time 6/8 
\tempo 4. = 96 
a4. a 
\time 4/4 

\tempo "Presto" 4 = 120 
a4 a a a 

> 


. And 

ante 

—1—1— 

J- = 96 

rn- 1 - k 

Pres 

to (d = 120) 

— 1 —1— — 

4 i • 



-T5-J 

=J=J=i 
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Clef 

Music Glossary: Section “clef” in Music Glossary. 
The clef can be set using the \clef command: 
\relative c 1 { 

\clef "treble" 
cl 

\clef "alto" 
cl 

\clef "tenor" 
cl 

\clef "bass" 
cl 

> 




All together 

Here is a small example showing all these elements together: 

\relative c, { 

\clef "bass" 

\time 3/4 

\tempo "Andante" 4 = 120 

c2 e8 c' 

g'2. 

f4 e d 

c4 c, r 

> 


Andante (J = 120) 


4 V «J ^ 

1 i 


H — Tn 

/• O 

L 

'9 ~ 

r 


■6 

-J- 



■9 



See also 

Notation Reference: Section “Writing pitches” in Notation Reference, Section “Writing 
rhythms” in Notation Reference, Section “Writing rests” in Notation Reference, Section “Time 
signature” in Notation Reference, Section “Clef” in Notation Reference. 

1.2.2 Working on input files 

LilyPond input files are similar to source files in many common programming languages. They 
contain a version statement, are case sensitive, and white-space is generally ignored. Expressions 
are formed with curly braces { }, and comments are denoted with °/ 0 or . . . ”/„} . 

If the previous sentences sound like nonsense, don’t worry! We’ll explain what all these terms 
mean: 

• Version statement: Every LilyPond file should contain a version statement. A version 
statement is a line that describes the version of LilyPond for which the file was written, as 
in the following example: 
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\version "2.18.2" 

By convention, the version statement is placed at the top of the LilyPond file. 

The version statement is important for at least two reasons. First, it allows automatic 
updating of the input file as LilyPond syntax changes. Second, it describes the version of 
LilyPond needed to compile the file. 

If the version statement is omitted from an input file, LilyPond will print a warning during 
the compilation of the file. 

• Case sensitive: it matters whether you enter a letter in lower case (e.g. a, b, s, t) or 
upper case (e.g. A, B, S, T). Notes are lower case: ‘{ c d e }’ is valid input; ‘{ C D E }’ 
will produce an error message. 

• Whitespace insensitive: it does not matter how many spaces (or tabs or new lines) you add. 

‘{ c4 d e }’ means the same thing as c4 d e }’ and: 

{ c4 d 

e } 

Of course, the previous example is hard to read. A good rule of thumb is to indent code 
blocks with two spaces: 

{ 

c4 d e 

> 

However, whitespace is required to separate many syntactical elements from others. In 
other words, whitespace can always be added , but not always eliminated. Since missing 
whitespace can give rise to strange errors, it is advisable to always insert whitespace before 
and after every syntactic element, for example, before and after every curly brace. 

• Expressions: every piece of LilyPond input needs to have { curly braces } placed around 
the input. These braces tell LilyPond that the input is a single music expression, just like 
parentheses () in mathematics. The braces should be surrounded by a space unless they 
are at the beginning or end of a line to avoid ambiguities. 

A LilyPond command followed by a simple expression in braces (such as 
‘\relative c 1 { ... }’) also counts as a single music expression. 

• Comments: a comment is a remark for the human reader of the music input; it is ignored 
while parsing, so it has no effect on the printed output. There are two types of comments. 
The percent symbol % introduces a line comment; anything after °/ 0 on that line is ignored. 
By convention, a line comment is placed above the code it refers to. 

a4 a a a 

7. this comment refers to the Bs 
b2 b 

A block comment marks a whole section of music input as a comment. Anything that is 
enclosed in %{ and is ignored. However, block comments do not ‘nest’. This means that 
you cannot place a block comment inside another block comment. If you try, the first %} will 
terminate both block comments. The following fragment shows possible uses for comments: 
7„ notes for twinkle twinkle follow 
c4 c g' g a a g2 


y.{ 

This line, and the notes below are ignored, 
since they are in a block comment. 

f4 f e e d d c2 

*/.} 
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1.3 Dealing with errors 

Sometimes LilyPond doesn’t produce the output you expect. This section provides some links 
to help you solve the problems you might encounter. 

1.3.1 General troubleshooting tips 

Troubleshooting LilyPond problems can be challenging for people who are used to a graphical 
interface, because invalid input files can be created. When this happens, a logical approach is 
the best way to identify and solve the problem. Some guidelines to help you learn to do this are 
provided in Section “Troubleshooting” in Application Usage. 

1.3.2 Some common errors 

There are a few common errors that are difficult to troubleshoot based simply on the error 
messages that are displayed. These are described in Section “Common errors” in Application 
Usage. 

1.4 How to read the manuals 

This section shows how to read the documentation efficiently, and also introduces some useful 
interactive features available in the online version. 

1.4.1 Omitted material 

LilyPond input must be surrounded by { } marks or a ‘\relative c' 1 { ... as we saw in 
Section 1.2.2 [Working on input hies], page 16. For the rest of this manual, most examples will 
omit this. To replicate the examples, you may copy and paste the displayed input, but you must 
add the ‘\relative c' 1 { ... }’ like this: 

\relative c 11 { 

...example goes here... 

> 

Why omit the braces? Most examples in this manual can be inserted into the 
middle of a longer piece of music. For these examples, it does not make sense to add 
‘\relative c 1 1 { ... }’ - you should not place a \relative inside another \relative! If 
we included ‘\relative c' ' { ... }’ around every example, you would not be able to copy a 
small documentation example and paste it inside a longer piece of your own. Most people want 
to add material to an existing piece, so we format the manual this way. 

Also, remember that every LilyPond hie should have a \version statement. Because the 
examples in the manuals are snippets, not hies, the \version statement is omitted. But you 
should make a practice of including them in your hies. 

1.4.2 Clickable examples 

{ \ 

Note: This feature is only available in the HTML manuals. 

v_y 

Many people learn programs by trying and hddling around with the program. This is also 
possible with LilyPond. If you click on a picture in the HTML version of this manual, you will 
see the exact LilyPond input that was used to generate that image. Try it on this image: 


c 


Click here. 
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By cutting and pasting everything in the “ly snippet” section, you have a starting template 
for experiments. To see exactly the same output (line-width and all), copy everything from 
“Start cut-&-pastable section” to the bottom of the file. 

1.4.3 Overview of manuals 

There is a lot of documentation for LilyPond. New users are sometimes confused about what 
part(s) they should read, and occasionally skip over reading vital portions. 

f \ 

Note: Please do not skip over important parts of the documentation. 

You will find it much harder to understand later sections, 
v_ 

• Before trying to do anything: read the Learning manual’s Chapter 1 [Tutorial], page 1, and 
Chapter 2 [Common notation], page 20. If you encounter musical terms which you do not 
recognize, please look them up in the Section “Glossary” in Music Glossary. 

• Before trying to write a complete piece of music: read the Learning manual’s Chapter 3 
[Fundamental concepts], page 40. After that, you may want to look in relevant sections of 
the Section “Notation reference” in Notation Reference. 

• Before trying to change the default output: read the Learning manual’s Chapter 4 [Tweak¬ 
ing output], page 86. 

• Before undertaking a large project: read the Usage document’s Section “Suggestions for 
writing files” in Application Usage. 
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2 Common notation 

This chapter explains how to create beautiful printed music containing common musical notation, 
following the material in Chapter 1 [Tutorial], page 1. 

2.1 Single staff notation 

This section introduces common notation that is used for one voice on one staff. 

2.1.1 Bar lines and bar checks 
Bar lines 

Single bar lines are automatically placed in the music so there is no need to add them manually. 
Other types of bar lines are added using \bar, for example \bar "II" for a double bar line, 
or \bar " | ." for an ending bar line. For a full list of bar lines see the Section “Bar lines” in 
Notation Reference. 

gl el \bar "II" c2. c'4 \bar "|." 



Bar checks 

Though not strictly necessary, bar checks should be used in the input code to show where bar 
lines are expected to fall. They are entered using the bar symbol, I. With bar checks, the 
program can verify that you’ve entered durations that make each measure add up to the correct 
length. Bar checks also make your input code easier to read, since they help to keep things 
organized. 

gl | el | c2. c'4 | g4 c g e I c4 r r2 | 



See also 

Notation Reference: Section “Bar and bar number checks” in Notation Reference. 

2.1.2 Accidentals and key signatures 

( \ 

Note: New users are often confused by these - please read the warning 
at the bottom of this page, especially if you are not familiar with music 
theory! 

V_ J 


Accidentals 

Music Glossary: Section “sharp” in Music Glossary , Section “flat” in Music Glossary, Section 
“double sharp” in Music Glossary, Section “double flat” in Music Glossary, Section “accidental” 
in Music Glossary. 

A sharp pitch is made by adding is to the name, and a flat pitch by adding es. As you 
might expect, a double sharp or double flat is made by adding isis or eses. This syntax is 
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derived from note naming conventions in Nordic and Germanic languages, like German and 
Dutch. To use other names for accidentals, see Section “Note names in other languages” in 
Notation Reference. 

cis4 ees fisis, aeses 



Key signatures 

Music Glossary: Section “key signature” in Music Glossary, Section “major” in Music Glossary, 
Section “minor” in Music Glossary. 

The key signature is set with the command \key followed by a pitch and \major or \minor. 
\key d \major 
al I 

\key c \minor 
al I 


-Hs - r 


}. — 



(iff) O 




Warning: key signatures and pitches 

Music Glossary: Section “accidental” in Music Glossary, Section “key signature” in Music Glos¬ 
sary, Section “pitch” in Music Glossary, Section “flat” in Music Glossary, Section “natural” in 
Music Glossary, Section “sharp” in Music Glossary, Section “transposition” in Music Glossary, 
Section “Pitch names” in Music Glossary. 

To determine whether to print an accidental, LilyPond examines the pitches and the key 
signature. The key signature only affects the printed accidentals, not the note’s pitch! This is 
a feature that often causes confusion to newcomers, so let us explain it in more detail. 

LilyPond makes a clear distinction between musical content and layout. The alteration (Sat, 
natural sign or sharp ) of a note is part of the pitch, and is therefore musical content. Whether 
an accidental (a printed flat, natural or sharp sign) is printed in front of the corresponding 
note is a question of layout. Layout is something that follows rules, so accidentals are printed 
automatically according to those rules. The pitches in your music are works of art, so they will 
not be added automatically, and you must enter what you want to hear. 

In this example: 

\key d \major 
cis4 d e fis 



No note has a printed accidental, but you must still add is and type cis and fis in the input 
file. 

The code b does not mean “print a black dot just on the middle line of the staff.” Rather, 
it means “there is a note with pitch B-natural.” In the key of A-flat major, it does get an 
accidental: 
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\key aes \major 
aes4 c b c 



If the above seems confusing, consider this: if you were playing a piano, which key would you 
hit? If you would press a black key, then you must add -is or -es to the note name! 

Adding all alterations explicitly might require a little more effort when typing, but the 
advantage is that transposing is easier, and accidentals can be printed according to different 
conventions. For some examples of how accidentals can be printed according to different rules, 
see Section “Automatic accidentals” in Notation Reference. 

See also 

Notation Reference: Section “Note names in other languages” in Notation Reference , Section 
“Accidentals” in Notation Reference, Section “Automatic accidentals” in Notation Reference, 
Section “Key signature” in Notation Reference. 

2.1.3 Ties and slurs 
Ties 

Music Glossary: Section “tie” in Music Glossary. 

A tie is created by appending a tilde ~ to the first note being tied. 
g4~ g c2~ | c4~ c8 a~ a2 | 



Slurs 

Music Glossary: Section “slur” in Music Glossary. 

A slur is a curve drawn across many notes. The starting note and ending note are marked 
with ( and ) respectively. 

d4( c!6) cis( dec cis d) e( d4) 



Phrasing slurs 

Music Glossary: Section “slur” in Music Glossary, Section “phrasing” in Music Glossary. 

Slurs to indicate longer phrasing can be entered with \( and \). You can have both slurs 
and phrasing slurs at the same time, but you cannot have simultaneous slurs or simultaneous 
phrasing slurs. 

g4\( g8( a) b( c) b4\) 
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Warnings: slurs vs. ties 

Music Glossary: Section “articulation” in Music Glossary, Section “slur” in Music Glossary , 
Section “tie” in Music Glossary. 

A slur looks like a tie, but it has a different meaning. A tie simply makes the first note longer, 
and can only be used on pairs of notes with the same pitch. Slurs indicate the articulation of 
notes, and can be used on larger groups of notes. Slurs and ties can be nested. 

c4~( c8 d~ d4 e) 



See also 

Notation Reference: Section “Ties” in Notation Reference, Section “Slurs” in Notation Ref¬ 
erence, Section “Phrasing slurs” in Notation Reference. 

2.1.4 Articulation and dynamics 

Articulations 

Music Glossary: Section “articulation” in Music Glossary. 

Common articulations can be added to a note using a dash - and a single character: 

c4-~ c-+ c— c-! 
c4-> c-. c2-_ 



Fingerings 

Music Glossary: Section “fingering” in Music Glossary. 

Similarly, fingering indications can be added to a note using a dash (-) and the digit to be 
printed: 

c4-3 e-5 b-2 a-1 



Articulations and fingerings are usually placed automatically, but you can specify a direction 
by replacing the dash (-) with ~ (up) or _ (down). You can also use multiple articulations on 
the same note. However, in most cases it is best to let LilyPond determine the articulation 
directions. 

c4_-~l d~. f"4_2-> e~-_+ 
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Dynamics 

Music Glossary: Section “dynamics” in Music Glossary, Section “crescendo” in Music Glossary, 
Section “decrescendo” in Music Glossary. 

Dynamic signs are made by adding the markings (with a backslash) to the note: 
c4\ff c\mf c\p c\pp 


/ e 

9 

9 

9 

9 




H 



ffmfPPP 


Crescendi and decrescendi are started with the commands \< and \>. The next dynamics 
sign, for example \f, will end the (de)crescendo, or the command \! can be used: 

c4\< c\ff\> c c\! 


E 




<ff 


See also 

Notation Reference: Section “Articulations and ornamentations” in Notation Reference, 
Section “Fingering instructions” in Notation Reference, Section “Dynamics” in Notation Refer¬ 
ence. 

2.1.5 Adding text 

Text may be added to your scores: 

c2~"espr" a_"legato" 



Extra formatting may be added with the \markup command: 

c2"\markup { \bold espr } 
a2_\markup { 

\dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p 

> 


A espr 

— 

rs 

r?—7 



u. 





f 2nd p 


See also 


Notation Reference: Section “Writing text” in Notation Reference. 
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2.1.6 Automatic and manual beams 

Music Glossary: Section “beam” in Music Glossary. 
All beams are drawn automatically: 
a8 ais d ees r d cl6 b a8 



If you do not like the automatic beams, they may be overridden manually. To correct just 
an occasional beam mark the first note to be beamed with [ and the last one with ]. 

a8[ ais] d[ ees r d] c!6 b a8 



If you want to turn off automatic beaming entirely or for an extended section of music, use 
the command \autoBeamOff to turn off automatic beaming and \autoBeamOn to turn it on 
again. 

\autoBeamOff 

a8 c b4 d8. cl6 b4 | 

\autoBeamOn 

a8 c b4 d8. c!6 b4 | 




3± 


p r Mr I cj r ^ 


See also 

Notation Reference: Section “Automatic beams” in Notation Reference , Section “Manual 
beams” in Notation Reference. 

2.1.7 Advanced rhythmic commands 

Partial measure 

Music Glossary: Section “anacrusis” in Music Glossary. 

A pickup (or anacrusis ) is entered with the keyword \partial. It is followed by a duration: 
\partial 4 is a quarter note pickup and \partial 8 an eighth note. 

\partial 8 f8 I 
c2 d I 
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Tuplets 


Music Glossary: Section “note value” in Music Glossary, Section “triplet” in Music Glossary. 


Tuplets are made with the \tuplet keyword. It takes two arguments: a fraction and a piece 
of music. The fraction is the number of triplet notes over the number of notes normally filling 
the same duration. For triplets, there are three notes instead of two, so triplets have 3/2 as 
their fraction. 


\tuplet 3/2 
\tuplet 3/2 
\tuplet 3/2 
\tuplet 3/2 


{ f8 g a } 
{ c8 r c } 
{ f,8 gl6 [ 
{ d4 a8 } 


a g a] 


> 



Grace notes 

Music Glossary: Section “grace notes” in Music Glossary, Section “acciaccatura” in Music 
Glossary, Section “appoggiatura” in Music Glossary. 

Grace notes are created with the \grace command, although they can also be created by 
prefixing a music expression with the keyword \appoggiatura or \acciaccatura: 
c2 \grace { a32 b } c2 | 
c2 \appoggiatura bl6 c2 | 
c2 \acciaccatura b!6 c2 | 



See also 

Notation Reference: Section “Grace notes” in Notation Reference, Section “Tuplets” in No¬ 
tation Reference, Section “Upbeats” in Notation Reference. 

2.2 Multiple notes at once 

This section introduces having more than one note at the same time: multiple instruments, 
multiple staves for a single instrument (i.e. piano), and chords. 

Polyphony in music refers to having more than one voice occurring in a piece of music. 
Polyphony in LilyPond refers to having more than one voice on the same staff. 

2.2.1 Music expressions explained 

In LilyPond input files, music is represented by music expressions. A single note is a music 
expression: 
a4 



Enclosing a note in braces creates a compound music expression. Here we have created a 
compound music expression with two notes: 
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{ a4 g4 } 



Putting a group of music expressions (e.g. notes) in braces means that they are in sequence 
(i.e. each one follows the previous one). The result is another music expression: 

{ { a4 g } f4 g } 



Analogy: mathematical expressions 

This mechanism is similar to mathematical formulas: a big formula is created by composing 
small formulas. Such formulas are called expressions, and they can contain other expressions, 
so you can make arbitrarily complex and large expressions. For example, 

1 

1 + 2 

(1 + 2) * 3 

((1 + 2) * 3) / (4 * 5) 

This is a sequence of expressions, where each expression is contained in the next (larger) one. 
The simplest expressions are numbers, and larger ones are made by combining expressions with 
operators (like +, * and /) and parentheses. Like mathematical expressions, music expressions 
can be nested arbitrarily deep, which is necessary for complex music like polyphonic scores. 

Simultaneous music expressions: multiple staves 

Music Glossary: Section “polyphony” in Music Glossary. 

This technique is useful for polyphonic music. To enter music with more voices or more 
staves, we combine expressions in parallel. To indicate that two voices should play at the same 
time, simply enter a simultaneous combination of music expressions. A ‘simultaneous’ music 
expression is formed by enclosing expressions inside << and >>. In the following example, three 
sequences (all containing two separate notes) are combined simultaneously: 

\relative c 11 { 

« 

{ a2 g } 

{ f2 e } 

{ d2 b } 

» 

> 
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Note that we have indented each level of the input with a different amount of space. LilyPond 
does not care how much (or little) space there is at the beginning of a line, but indenting LilyPond 
code like this makes it much easier for humans to read. 

( \ 

Note: each note is relative to the previous note in the input, only the 
first is relative to the c' 1 in the initial \relative command. 

V_/ 


Simultaneous music expressions: single staff 

To determine the number of staves in a piece, LilyPond looks at the beginning of the first 
expression. If there is a single note, there is one staff; if there is a simultaneous expression, there 
is more than one staff. The following example shows a complex expression, but as it begins with 
a single note it will be set out on a single staff. 

\relative c 11 { 
c2 <<c e>> I 

« { e2 f } { c2 «b d» } » | 

> 



2.2.2 Multiple staves 

LilyPond input files are constructed out of music expressions, as we saw in Section 2.2.1 [Music 
expressions explained], page 26. If the score begins with simultaneous music expressions, Lily¬ 
Pond creates multiples staves. However, it is easier to see what happens if we create each staff 
explicitly. 

To print more than one staff, each piece of music that makes up a staff is marked by adding 
\new Staff before it. These Staff elements are then combined in parallel with « and »: 

\relative c 11 { 

« 

\new Staff { \clef "treble" c4 } 

\new Staff { \clef "bass" c,,4 } 

» 


0 


> 
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The command \new introduces a ‘notation context.’ A notation context is an environment 
in which musical events (like notes or \clef commands) are interpreted. For simple pieces, 
such notation contexts are created automatically. For more complex pieces, it is best to mark 
contexts explicitly. 

There are several types of contexts. Score, Staff, and Voice handle melodic notation, while 
Lyrics sets lyric texts and ChordNames prints chord names. 

In terms of syntax, prepending \new to a music expression creates a bigger music expression. 
In this way it resembles the minus sign in mathematics. The formula (4 + 5) is an expression, 
so — (4 + 5) is a bigger expression. 

Time signatures entered in one staff affect all other staves by default. On the other hand, the 
key signature of one staff does not affect other staves. This different default behavior is because 
scores with transposing instruments are more common than polyrhythmic scores. 

\relative c 11 { 

« 

\new Staff { \clef "treble" \key d \major \time 3/4 c4 } 

\new Staff { \clef "bass" c,,4 } 

» 

> 



2.2.3 Staff groups 

Music Glossary: Section “brace’’ in Music Glossary, Section “staff” in Music Glossary, Section 
“system” in Music Glossary. 

Piano music is typeset in two staves connected by a brace. Printing such a staff is similar 
to the polyphonic example in Section 2.2.2 [Multiple staves], page 28. However, now this entire 
expression is inserted inside a PianoStaff: 

\new PianoStaff « 

\new Staff ... 

\new Staff ... 

» 

Here is a small example: 

\relative c 11 { 

\new PianoStaff « 

\new Staff { \time 2/4 c4 e | g g, I } 

\new Staff { \clef "bass" c,,4 c' | e c | } 
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Other staff groupings are introduced with \new GrandStaff, suitable for orchestral scores, 
and \new Choir Staff, suitable for vocal scores. These staff groups each form another type of 
context, one that generates the brace at the left end of every system and also controls the extent 
of bar lines. 

See also 

Notation Reference: Section “Keyboard and other multi-staff instruments” in Notation Ref¬ 
erence , Section “Displaying staves” in Notation Reference. 

2.2.4 Combining notes into chords 

Music Glossary: Section “chord” in Music Glossary 

We saw earlier how notes can be combined into chords by indicating they are simultaneous 
by enclosing them in double angle brackets. However, the normal way of indicating a chord is 
to surround the pitches with single angle brackets. Note that all the notes in a chord must have 
the same duration, and that the duration is placed after the closing bracket. 

r4 <c e g> <c f a>2 



Think of chords as almost equivalent to single notes: almost everything you can attach to 
a single note can be attached to a chord, and everything must go outside the angle brackets. 
For example, you can combine markings like beams and ties with chords. They must be placed 
outside the angle brackets. 

r4 <c e g>~ <c f a>2 I 

<c e g>8[ <c f a> <c e g> <c f a>] 

<c e g>8\> [ <c f a> <c f a> <c e g>]\! I 
r4 <c e g>8.\p <c f a>16( <c e g>4-. <c f a>) | 


-Jf— n —>- 


»- T 

ti 

Pr 

ffi 

h 

f 

PH 

* 

f-1 

> i 1 

HH 


c; f — 















P 


See also 

Notation Reference: Section “Chorded notes” in Notation Reference. 

2.2.5 Single staff polyphony 

Polyphonic music in lilypond, while not difficult, uses concepts that we haven’t discussed yet, so 
we’re not going to introduce them here. Instead, the following sections introduce these concepts 
and explain them thoroughly. 

See also 

Learning Manual: Section 3.2 [Voices contain music], page 46. 

Notation Reference: Section “Simultaneous notes” in Notation Reference. 
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2.3 Songs 

This section introduces vocal music and simple song sheets. 

2.3.1 Setting simple songs 

Music Glossary: Section “lyrics” in Music Glossary. 

Here is the start of the melody to a nursery rhyme, Girls and boys come out to play: 

\relative c 11 { 

\key g \major 
\time 6/8 

d4 b8 c4 a8 | d4 b8 g4 



The lyrics can be set to these notes, combining both with the \addlyrics keyword. Lyrics 
are entered by separating each syllable with a space. 

« 

\relative c 1 ' { 

\key g \major 
\time 6/8 

d4 b8 c4 a8 | d4 b8 g4 

> 

\addlyrics { 

Girls and boys come | out to play, 

> 



Girls and boys come out to play, 


Note the double angle brackets «. . .» around the whole piece to show that the music and 
lyrics are to occur at the same time. 

2.3.2 Aligning lyrics to a melody 

Music Glossary: Section “melisma” in Music Glossary , Section “extender line” in Music Glos¬ 
sary. 

The next line in the nursery rhyme is The moon doth shine as bright as day. Let’s extend it: 

« 

\relative c 1 ' { 

\key g \major 
\time 6/8 

d4 b8 c4 a8 | d4 b8 g4 g8 | 
a4 b8 c b a | d4 b8 g4. | 

> 

\addlyrics { 

Girls and boys come | out to play, 
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The | moon doth shine as | bright as day; | 

> 

» 



Girls and boys come out to play, The 


JHH 




A ^ 



W m 




Ms_ m 



9 m 



• 


^- 

—4 r — 1 

-•— 



moon doth shine as bright as day; 


If you compile the code in the example above, you should see some warnings in the console 
output: 

song.ly:12:29: warning: barcheck failed at: 5/8 
The | moon doth shine as 

I bright as day; | 
song.ly:12:46: warning: barcheck failed at: 3/8 
The | moon doth shine as I bright as day; 

I 

This is a good example of the usefulness of bar checks. Now, looking at the music, we see 
that the extra lyrics do not align properly with the notes. The word shine should be sung on 
two notes, not one. This is called a melisma, a single syllable sung to more than one note. There 
are several ways to spread a syllable over multiple notes, the simplest being to add a slur across 
them, for details, see Section 2.1.3 [Ties and slurs], page 22: 

« 

\relative c 1 ' { 

\key g \major 
\time 6/8 

d4 b8 c4 a8 | d4 b8 g4 g8 | 
a4 b8 c( b) a | d4 b8 g4. | 

> 

\addlyrics { 

Girls and boys come | out to play, 

The | moon doth shine as I bright as day; | 

> 

» 


-HHhr 

- 

s - r 



\ 

-Ar4 

F 


ft - 

r j 

1- 



F- 

VU c 

> 

— 

v — 


V 


Girls and boys come out to play, The 



moon doth shine as bright as day; 


The words now line up correctly with the notes, but the automatic beaming for the notes 
above shine as does not look right. We can correct this by inserting manual beaming commands 
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to override the automatic beaming here, for details, see Section 2.1.6 [Automatic and manual 
beams], page 25. 

« 

\relative c 1 ' { 

\key g \major 
\time 6/8 

d4 b8 c4 a8 | d4 b8 g4 g8 | 
a4 b8 c([ b]) a | d4 b8 g4. | 

> 

\addlyrics { 

Girls and boys come | out to play, 

The | moon doth shine as | bright as day; | 

> 

» 


V tt ti , 

m -—- 

.-h—= 

m --- 


\ — 


r p 

■- j 1 — 

li 

- m 

1— 


Girls and boys come out to play, The 



moon doth shine as bright as day; 


As an alternative to using slurs, the melismata may be indicated in just the lyrics by using 
an underscore _ for each note that should be included in the melisma: 

« 

\relative c 1 ' { 

\key g \major 
\time 6/8 

d4 b8 c4 a8 | d4 b8 g4 g8 | 
a4 b8 c [ b] a | d4 b8 g4. | 

> 

\addlyrics { 

Girls and boys come | out to play, 

The | moon doth shine _ as | bright as day; I 

> 

» 



Girls and boys come out to play, The 



moon doth shine as bright as day; 


If a syllable extends over several notes or a single very long note an extender line is usually 
drawn from the syllable extending under all the notes for that syllable. It is entered as two 
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underscores_. Here is an example from the first three bars of Dido’s Lament , from Purcell’s 

Dido and JEneas: 

« 

\relative c' 1 { 

\key g \minor 
\time 3/2 

g2 a bes | bes2( a) b2 | 

c4.( bes8 a4. g8 fis4.) g8 | fisl 

> 

\addlyrics { 

When I am | laid, 

am | laid _ in | earth, 

> 

» 


-fih 

i 


1-1 

1— ^ 

|— - 


— y - 



s 



f 


1 






m • ^ _ 


) 

1 

\ 

(rr\ v e 

1_£ 

_ & 


r 

Ij 

r V 

u 

r 


■n 

• ^ 

1 LL 



vR A 

■ 

f _ 



□ 





J — uw 


tto_ 

When I 

1 1 

am 

laid, £ 

1 

im 

laic 

f ti n 

[ in earth, 


None of the examples so far have involved words containing more than one syllable. Such 
words are usually split one syllable to a note, with hyphens between syllables. Such hyphens are 
entered as two dashes, resulting in a centered hyphen between the syllables. Here is an example 
showing this and everything we have learned so far about aligning lyrics to notes. 

« 

\relative c' { 

\key g \major 
\time 3/4 
\partial 4 

d4 | g4 g a8( b) I g4 g b8( c) I 
d4 d e | c2 

> 

\addlyrics { 

A — I way in a _ I man — ger, 

no _ I crib for a | bed, 

> 

» 



A - way in a_ man-ger, no crib for a bed, 

Some lyrics, especially those in Italian, require the opposite: setting more than one syllable 
to a single note. This is achieved by linking the syllables together with a single underscore 
(with no spaces), or enclosing them in quotes. Here’s an example from Rossini’s Figaro, where 
a 1 has to be sung on the same note as the go of Largo in Figaro’s aria Largo a 1 factotum: 

« 

\relative c' { 

\clef "bass" 

\key c \major 
\time 6/8 
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c4.~ c8 d b | c8([ d]) b c d b I c8 

> 

\addlyrics { 

Lar — go_al fac — | to — turn del — la cit — | ta 

> 


4 v <4 

-f -——i 

f f ft—r f r 

rf— 


J 

i 

VL 


3 


Lar - go al fac - to - turn del - la cit - ta 


See also 

Notation Reference: Section “Vocal music” in Notation Reference. 

2.3.3 Lyrics to multiple staves 

The simple approach using \addlyrics can be used for placing lyrics under more than one staff. 
Here is an example from Handel’s Judas Maccabaeus: 

« 

\relative c 1 ' { 

\key f \major 
\time 6/8 
\partial 8 

c8 I c8([ bes]) a a([ g]) f I f'4. b, I c4.~ c4 

> 

\addlyrics { 

Let | flee — cy flocks the | hills a — | dorn, 

> 

\relative c' { 

\key f \major 
\time 6/8 
\partial 8 

r8 I r4. r4 c8 | a'8([ g]) f f([ e]) d I e8([ d]) c bes'4 

> 

\addlyrics { 

Let | flee — cy flocks the | hills a — dorn, 




Y i f r 


Let flee cy flocks the hills a 


dorn, 


i 


mm 


Let flee cy flocks the hills adorn, 


Scores any more complex than this simple example are better produced by separating out 
the score structure from the notes and lyrics with variables. These are discussed in Section 2.4.1 
[Organizing pieces with variables], page 36. 
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See also 

Notation Reference: Section “Vocal music” in Notation Reference. 

2.4 Final touches 

This is the final section of the tutorial; it demonstrates how to add the final touches to simple 
pieces, and provides an introduction to the rest of the manual. 

2.4.1 Organizing pieces with variables 

When all of the elements discussed earlier are combined to produce larger files, the music ex¬ 
pressions get a lot bigger. In polyphonic music with many staves, the input files can become 
very confusing. We can reduce this confusion by using variables. 

With variables (also known as identifiers or macros), we can break up complex music expres¬ 
sions. A variable is assigned as follows: 

namedMusic = { ... } 

The contents of the music expression namedMusic can be used later by placing a backslash 
in front of the name (\namedMusic, just like a normal LilyPond command). 

violin = \new Staff { 

\relative c 1 ' { 
a4 b c b 

> 

> 

cello = \new Staff { 

\relative c { 

\clef "bass" 
e2 d 

> 

> 

{ 

« 

\violin 

\cello 

» 

> 



The name of a variable must have alphabetic characters only, no numbers, underscores, or 
dashes. 

Variables must be defined before the main music expression, but may be used as many times 
as required anywhere after they have been defined. They may even be used in a later definition 
of another variable, giving a way of shortening the input if a section of music is repeated many 
times. 
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tripletA = \tuplet 3/2 { c,8 e g } 

barA = { \tripletA \tripletA \tripletA \tripletA } 


\relative c 11 { 
\barA \barA 

> 



Variables may be used for many other types of objects in the input. For example, 

width = 4.5\cm 
name = "Wendy" 

aFivePaper = \paper { paperheight =21.0 \cm } 

Depending on its contents, the variable can be used in different places. The following example 
uses the above variables: 

\paper { 

\aFivePaper 
line-width = \width 

> 

{ 

c4~\name 

> 

2.4.2 Adding titles 

The title, composer, opus number, and similar information are entered in the \header block. 
This exists outside of the main music expression; the \header block is usually placed underneath 
the version number. 

\version "2.18.2" 

\header { 

title = "Symphony" 
composer = "Me" 
opus = "Op. 9" 

> 

{ 

... music ... 

> 

When the file is processed, the title and composer are printed above the music. More in¬ 
formation on titling can be found in Section “Creating titles headers and footers” in Notation 
Reference. 

2.4.3 Absolute note names 

So far we have always used \relative to define pitches. This is usually the fastest way to enter 
most music. Without \relative, pitches are interpreted in absolute mode. 

In this mode, LilyPond treats all pitches as absolute values. A c' will always mean middle 
C, a b will always mean the note one step below middle C, and a g, will always mean the note 
on the bottom staff of the bass clef. 
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{ 

\clef "bass" 
c'4 bg, g, | 
g,4 f, f c' | 

} 


4): „ 

9 _ 

j-, 



-m - 

s i — 

-J 






Here is a four-octave scale: 


{ 

\clef "bass" 
c,4 d, e, f, | 
g,4 a, b, c | 
d4 e f g | 
a4 b c 1 d 1 I 
\clef "treble" 
e'4 f' g 1 a' | 
b 1 4 c " d'' e' 1 
f "4 g" a' 1 b' ' 
c' ' ' 1 I 

> 




As you can see, writing a melody in the treble clef involves a lot of quote ' marks. Consider 
this fragment from Mozart: 

{ 

\key a \major 
\time 6/8 

cis' '8. d"16 cis"8 e"4 e"8 I 
b 1 8. cis"16 b'8 d"4 d"8 I 

> 



All these quotes makes the input less readable and they are a source of errors. With 
\relative, the previous example is much easier to read and type: 

\relative c 11 { 

\key a \major 
\time 6/8 

cis8. dl6 cis8 e4 e8 | 
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b8. cisl6 b8 d4 d8 | 

> 



If you make a mistake with an octave mark (' or ,) while working in \relative mode, it 
is very obvious - many notes will be in the wrong octave. When working in absolute mode, a 
single mistake will not be as visible, and will not be as easy to find. 

However, absolute mode is useful for music which has large intervals, and is extremely useful 
for computer-generated LilyPond files. When cutting and pasting melody fragments, absolute 
mode preserves the original octave. 

Sometimes music is arranged in more complex ways. If you are using \relative inside of 
\relative, the outer and inner relative sections are independent: 

\relative c { c'4 \relative c' 1 { f g } c } 



If you are using absolute music inside of relative, you’ll need to mark the absolute music 
explicitly with \absolute to stop it from becoming part of the relative music: 

\relative c { c'4 \absolute { f 11 g'' } c } 


0 




2.4.4 After the tutorial 

After finishing the tutorial, you should probably try writing a piece or two. Start by adding 
notes to one of the Appendix A [Templates], page 146. If you need any notation that was not 
covered in the tutorial, look at the Notation Reference, starting with Section “Musical notation” 
in Notation Reference. If you want to write for an instrument ensemble that is not covered in 
the templates, take a look at Section 3.4 [Extending the templates], page 69. 

Once you have written a few short pieces, read the rest of the Learning Manual (chapters 3-5). 
There’s nothing wrong with reading it now, of course! However, the rest of the Learning Manual 
assumes that you are familiar with LilyPond input. You may wish to skim these chapters right 
now, and come back to them after you have more experience. 

In this tutorial and in the rest of the Learning Manual, there is a paragraph See also at 
the end of each section, which contains cross-references to other sections: you should not follow 
these cross-references at first reading; when you have read all of the Learning Manual, you may 
want to read some sections again and follow cross-references for further reading. 

If you have not done so already, please read Section 1.4.3 [Overview of manuals], page 19. 
There is a lot of information about LilyPond, so newcomers often do not know where they should 
look for help. If you spend five minutes reading that section carefully, you might save yourself 
hours of frustration looking in the wrong places! 
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3 Fundamental concepts 

You’ve seen in the Tutorial how to produce beautifully printed music from a simple text hie. 
This section introduces the concepts and techniques required to produce equally beautiful but 
more complex scores. 

3.1 How LilyPond input files work 

The LilyPond input format is quite free-form, giving experienced users a lot of flexibility to 
structure their hies however they wish. But this flexibility can make things confusing for new 
users. This section will explain some of this structure, but may gloss over some details in favor 
of simplicity. For a complete description of the input format, see Section “File structure” in 
Notation Reference. 

3.1.1 Introduction to the LilyPond file structure 

A basic example of a LilyPond input hie is 
\version "2.18.2" 

\header { } 

\score { 

... compound music expression ... % all the music goes here! 

\layout { } 

\midi { } 

> 

There are many variations of this basic pattern, but this example serves as a useful starting 
place. 

Up to this point none of the examples you have seen have used a \score-Q command. This 
is because LilyPond automatically adds the extra commands which are needed when you give it 
simple input. LilyPond treats input like this: 

\relative c 11 { 
c4 a d c 

> 

as shorthand for this: 

\book { 

\score { 

\new Staff { 

\new Voice { 

\relative c 11 { 
c4 a b c 

> 

> 

} 

May out { } 

> 

> 

In other words, if the input contains a single music expression, LilyPond will interpret the 
hie as though the music expression was wrapped up inside the commands shown above. 

A word of warning! Many of the examples in the LilyPond documentation will omit the \new 
Staff and \new Voice commands, leaving them to be created implicitly. For simple examples 
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this works well, but for more complex examples, especially when additional commands are used, 
the implicit creation of contexts can give surprising results, maybe creating extra unwanted 
staves. The way to create contexts explicitly is explained in Section 3.3 [Contexts and engravers], 
page 57. 

C \ 

Note: When entering more than a few lines of music it is advisable to 

always create staves and voices explicitly. 

\_y 

For now, though, let us return to the first example and examine the \score command, leaving 
the others to default. 

A \score block must always contain exactly one music expression. Remember that a music 
expression could be anything from a single note to a huge compound expression like 

{ 

\new StaffGroup « 

... insert the whole score of a Wagner opera in here ... 

» 

} 

Since everything is inside { ... }, it counts as one music expression. 

As we saw previously, the \score block can contain other things, such as 

\score { 

{ c'4 a b c' > 

\header { } 

\layout { } 

\midi { } 

> 

Note that these three commands - \header, \layout and \midi - are special: unlike many 
other commands which begin with a backward slash (\) they are not music expressions and are 
not part of any music expression. So they may be placed inside a \score block or outside it. In 
fact, these commands are commonly placed outside the \score block - for example, \header is 
often placed above the \score command, as the example at the beginning of this section shows. 

Two more commands you have not previously seen are \layout { } and \midi {}. If these 
appear as shown they will cause LilyPond to produce a printed output and a MIDI output 
respectively. They are described fully in the Notation Reference - Section “Score layout” in 
Notation Reference, and Section “Creating MIDI files” in Notation Reference. 

You may code multiple \score blocks. Each will be treated as a separate score, but they 
will be all combined into a single output file. A \book command is not necessary - one will 
be implicitly created. However, if you would like separate output files from one ‘. ly’ file then 
the \book command should be used to separate the different sections: each \book block will 
produce a separate output file. 

In summary: 

Every \book block creates a separate output file (e.g., a PDF file). If you haven’t explicitly 
added one, LilyPond wraps your entire input code in a \book block implicitly. 

Every \score block is a separate chunk of music within a \book block. 

Every \layout block affects the \score or \book block in which it appears - i.e., a \layout 
block inside a \score block affects only that \score block, but a \layout block outside of a 
\score block (and thus in a \book block, either explicitly or implicitly) will affect every \score 
in that \book. 

For details see Section “Multiple scores in a book” in Notation Reference. 
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Another great shorthand is the ability to define variables, as shown in Section 2.4.1 [Orga¬ 
nizing pieces with variables], page 36. All the templates use this: 

melody = \relative c 1 { 
c4 a b c 

> 

\score { 

\melody 

> 

When LilyPond looks at this file, it takes the value of melody (everything after the equals 
sign) and inserts it whenever it sees \melody. There’s nothing special about the name - it could 
be melody, global, keyTime, pianorighthand, or something else. Remember that you can use 
almost any name you like as long as it contains just alphabetic characters and is distinct from 
LilyPond command names. For more details, see Section 3.4.4 [Saving typing with variables 
and functions], page 82. The exact limitations on variable names are detailed in Section “File 
structure” in Notation Reference. 

See also 

For a complete definition of the input format, see Section “File structure” in Notation Ref¬ 
erence. 

3.1.2 Score is a (single) compound musical expression 

We saw the general organization of LilyPond input files in the previous section, Section 3.1.1 
[Introduction to the LilyPond file structure], page 40. But we seemed to skip over the most 
important part: how do we figure out what to write after \score? 

We didn’t skip over it at all. The big mystery is simply that there is no mystery. This line 
explains it all: 

A \score block must contain exactly one music expression. 

To understand what is meant by a music expression, you may find it useful to review the tutorial, 
Section 2.2.1 [Music expressions explained], page 26. In that section, we saw how to build big 
music expressions from small pieces - we started from notes, then chords, etc. Now we’re going 
to start from a big music expression and work our way down. For simplicity, we’ll use just a 
singer and piano in our example. We don’t need a StaffGroup for this ensemble, which simply 
groups a number of staves together with a bracket at the left, but we do need staves for a singer 
and a piano, though. 

\score { 

« 

\new Staff = "singer" << 

>> 

\new PianoStaff = "piano" « 

>> 

» 

\layout { } 

> 

Here we have given names to the staves - “singer” and “piano”. This is not essential here, 
but it is a useful habit to cultivate so that you can see at a glance what each stave is for. 

Remember that we use << ... >> instead of { . . . } to show simultaneous music. This 
causes the vocal part and piano part to appear one above the other in the score. The << ... » 
construct would not be necessary for the Singer staff in the example above if it were going to 
contain only one sequential music expression, but << ... » rather than braces is necessary if 
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the music in the Staff is to contain two or more simultaneous expressions, e.g. two simultaneous 
Voices, or a Voice with lyrics. We’re going to have a voice with lyrics, so angle brackets are 
required. We’ll add some real music later; for now let’s just put in some dummy notes and 
lyrics. If you’ve forgotten how to add lyrics you may wish to review \addlyrics in Section 2.3.1 
[Setting simple songs], page 31. 

\score { 

« 

\new Staff = "singer" << 

\new Voice = "vocal" { c 1 1 } 

\addlyrics { And } 

>> 

\new PianoStaff = "piano" « 

\new Staff = "upper" { c 1 1 } 

\new Staff = "lower" { c'l } 

>> 

» 

\layout { } 

> 



Now we have a lot more details. We have the singer’s staff: it contains a Voice (in LilyPond, 
this term refers to a set of notes, not necessarily vocal notes - for example, a violin generally 
plays one voice) and some lyrics. We also have a piano staff: it contains an upper staff (right 
hand) and a lower staff (left hand), although the lower staff has yet to be given a bass clef. 

At this stage, we could start filling in notes. Inside the curly braces next to \new Voice = 
"vocal", we could start writing 
\relative c 11 { 

r4 d8\noBeam g, c4 r 

> 

But if we did that, the \score section would get pretty long, and it would be harder to 
understand what was happening. So let’s use variables instead. These were introduced at 
the end of the previous section, remember? To ensure the contents of the text variable are 
interpreted as lyrics we preface them with \lyricmode. Like \addlyrics, this switches the 
input mode to lyrics. Without that, LilyPond would try to interpret the contents as notes, 
which would generate errors. (Several other input modes are available, see Section “Input 
modes” in Notation Reference.) 

So, adding a few notes and a bass clef for the left hand, we now have a piece of real music: 

melody = \relative c 1 ' { r4 d8\noBeam g, c4 r } 

text = \lyricmode { And God said, } 

upper = \relative c 1 ' { <g d g,>2~ <g d g,> } 

lower = \relative c { b2 e } 
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\score { 

« 

\new Staff = "singer" << 

\new Voice = "vocal" { \melody } 
\addlyrics { \text } 

>> 

\new PianoStaff = "piano" « 

\new Staff = "upper" { \upper } 
\new Staff = "lower" { 

\clef "bass" 

\lower 

> 

>> 

» 

May out { } 


JEEFEE^ 


E-f- 


And God said, 


—(S- 




When writing (or reading) a \score section, just take it slowly and carefully. Start with the 
outer level, then work on each smaller level. It also really helps to be strict with indentation - 
make sure that each item on the same level starts on the same horizontal position in your text 
editor. 

See also 

Notation Reference: Section “Structure of a score” in Notation Reference. 

3.1.3 Nesting music expressions 

It is not essential to declare all staves at the beginning; they may be introduced temporarily at 
any point. This is particularly useful for creating ossia sections - see Section “ossia” in Music 
Glossary. Here is a simple example showing how to introduce a new staff temporarily for the 
duration of three notes: 

\new Staff { 

\relative g' { 
r4 g8 g c4 c8 d I 
e4 r8 
<< 

{ f8 c c } 

\new Staff { 
f8 f c 

> 

>> 
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r4 | 

> 



Note that the size of the clef is the same as a clef printed following a clef change - slightly 
smaller than the clef at the beginning of the line. This is usual for clefs printed in the middle of 
a line. 

The ossia section may be placed above the staff as follows: 

\new Staff = "main" { 

\relative g' { 
r4 g8 g c4 c8 d I 
e4 r8 
<< 

{ f8 c c } 

\new Staff \with { 

alignAboveContext = #"main" 

} { f8 f c } 

>> 
r4 I 

> 

> 




This example uses \with, which will be explained more fully later. It is a means of modifying 
the default behavior of a single Staff. Here it says that the new staff should be placed above the 
staff called “main” instead of the default position which is below. 

See also 

Ossia are often written without clef and without time signature and are usually in a smaller 
font. These require further commands which have not yet been introduced. See Section 4.3.2 
[Size of objects], page 102, and Section “Ossia staves” in Notation Reference. 

3.1.4 On the un-nestedness of brackets and ties 

You have already met a number of different types of bracket and bracket-like constructs in 
writing the input file to LilyPond. These obey different rules which can be confusing at first. 
Let’s first review the different types of brackets and bracket-like constructs. 


Bracket Type 


Function 
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{ . 

.. > 

Encloses a sequential segment of music 

< . 

. . > 

Encloses the notes of a chord 

<< 

...» 

Encloses simultaneous music expressions 

( . 

.. ) 

Marks the start and end of a slur 

\( 

... \) 

Marks the start and end of a phrasing slur 

[ . 

.. ] 

Marks the start and end of a manual beam 


To these we should add other constructs which generate lines between or across notes: ties 
(marked by a tilde, ~), tuplets written as \tuplet x/y {...}, and grace notes written as 
\grace {...}. 

Outside LilyPond, the conventional use of brackets requires the different types to be properly 
nested, like this, << [ { ( ... ) } ] », with the closing brackets being encountered in exactly 
the opposite order to the opening brackets. This is a requirement for the three types of bracket 
described by the word ‘Encloses’ in the table above - they must nest properly. However, the 
remaining bracket-like constructs, described with the word ‘Marks’ in the table above together 
with ties and tuplets, do not have to nest properly with any of the brackets or bracket-like 
constructs. In fact, these are not brackets in the sense that they enclose something - they are 
simply markers to indicate where something starts and ends. 

So, for example, a phrasing slur can start before a manually inserted beam and end before 
the end of the beam - not very musical, perhaps, but possible: 

g8\( a b[ c b\) a] g4 



In general, different kinds of brackets, bracket-like constructs, and those implied by tuplets, 
ties and grace notes, may be mixed freely. This example shows a beam extending into a triplet 
(line 1), a slur extending into a triplet (line 2), a beam and a slur extending into a tuplet, a tie 
crossing two triplets, and a phrasing slur extending out of a triplet (lines 3 and 4). 

rl6[ g \tuplet 3/2 { rl6 e 1 8] } 
g,16( a \tuplet 3/2 { bl6 d) e } 
g,8[( a \tuplet 3/2 { b8 d) e~] > I 
\tuplet 5/4 { e32\( a, b d e } a4.\) 




3.2 Voices contain music 

Singers need voices to sing, and so does LilyPond. The actual music for all instruments in a 
score is contained in Voices - the most fundamental of all LilyPond’s concepts. 
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3.2.1 I’m hearing Voices 

The lowest, most fundamental or innermost layers in a LilyPond score are called ‘Voice contexts’ 
or just ‘Voices’ for short. Voices are sometimes called ‘layers’ in other notation packages. 

In fact, a Voice layer or context is the only one which can contain music. If a Voice context is 
not explicitly declared one is created automatically, as we saw at the beginning of this chapter. 
Some instruments such as an Oboe can play only one note at a time. Music written for such 
instruments requires just a single voice. Instruments which can play more than one note at a 
time like the piano will often require multiple voices to encode the different concurrent notes 
and rhythms they are capable of playing. 

A single voice can contain many notes in a chord, of course, so when exactly are multiple 
voices needed? Look first at this example of four chords: 

\key g \major 

<d g>4 <d fis> <d a’> <d g> 



This can be expressed using just the single angle bracket chord symbols, < ... >, and for 
this just a single voice is needed. But suppose the F-sharp were actually an eighth-note followed 
by an eighth-note G, a passing note on the way to the A? Now we have two notes which start 
at the same time but have different durations: the quarter-note D and the eighth-note F-sharp. 
How are these to be coded? They cannot be written as a chord because all the notes in a chord 
must have the same duration. And they cannot be written as two sequential notes as they need 
to start at the same time. This is when two voices are required. 

Let us see how this is done in LilyPond input syntax. 

The easiest way to enter fragments with more than one voice on a staff is to enter each voice 
as a sequence (with { ... }), and combine them simultaneously with angle brackets, << . . . 
». The fragments must also be separated with double backward slashes, \\, to place them in 
separate voices. Without these, the notes would be entered into a single voice, which would 
usually cause errors. This technique is particularly suited to pieces of music which are largely 
homophonic with occasional short sections of polyphony. 

Here’s how we split the chords above into two voices and add both the passing note and a 
slur: 

\key g \major 

°/„ Voice "1" Voice "2" 

<< { g4 fis8( g) a4 g } \\ { d4 d d d } >> 



Notice how the stems of the second voice now point down. 


Here’s another simple example: 


\key d \minor 
% Voice "1" 

« { r4 g g4. a8 > \\ 
<< { bes4 bes c bes } \\ 
« { a2. r4 } \\ 


Voice "2" 

{ d,2 d4 g } » I 
{ g4 g g8( a) g4 } » I 
{ fis2. s4 } » I 
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It is not necessary to use a separate « \\ >> construct for each bar. For music with few 
notes in each bar this layout can help the legibility of the code, but if there are many notes in 
each bar it may be better to split out each voice separately, like this: 

\key d \minor 

« 4 

7. Voice "1" 
r4 g g4. a8 | 
bes4 bes c bes | 
a2. r4 | 

> \\ 4 

7. Voice "2" 
d,2 d4 g | 
g4 g g8( a) g4 | 
fis2. s4 | 

> » 



This example has just two voices, but the same construct may be used to encode three or 
more voices by adding more back-slash separators. 

The Voice contexts bear the names "1", "2", etc. The first contexts set the outer voices, the 
highest voice in context " 1" and the lowest voice in context " 2". The inner voices go in contexts 
"3" and "4". In each of these contexts, the vertical direction of slurs, stems, ties, dynamics etc., 
is set appropriately. 

\new Staff \relative c' 4 
7o Main voice 
cl6 d e f 

7. Voice "1" Voice "2" Voice "3" 

« 4 g4 f e } \\ 4 r8 e4 d c8~ } » | 

« 4 d2 e } \\ 4 c8 bl6 a b8 g~ g2 } \\ 4 s4 b c2 } » I 

> 



u* 4 * r V 



T 


These voices are all separate from the main voice that contains the notes just outside the « 
...» construct. Let’s call this the simultaneous construct. Slurs and ties may only connect 
notes within the same voice, so slurs and ties cannot go into or out of a simultaneous construct. 
Conversely, parallel voices from separate simultaneous constructs on the same staff are the same 
voice. Other voice-related properties also carry across simultaneous constructs. Here is the same 
example, with different colors and note heads for each voice. Note that changes in one voice do 
not affect other voices, but they do persist in the same voice later. Note also that tied notes 
may be split across the same voices in two constructs, shown here in the blue triangle voice. 
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\new Staff \relative c' { 
% Main voice 
cl6 d e f 
« 7. Bar 1 

{ 

\voiceOneStyle 
g4 f e 

} 

\\ 

{ 

\voiceTwoStyle 
r8 e4 d c8~ 

} 

» I 

« 7. Bar 2 

7o Voice 1 continues 
{ d2 e } 

\\ 

7o Voice 2 continues 
{ c8 bl6 a b8 g~ g2 } 

\\ 

{ 

\voiceThreeStyle 
s4 b c2 

} 

» I 

> 


X i* ss g | 1 | 


VI V . > 



^ ) r r 




The commands \voiceXXXStyle are mainly intended for use in educational documents such 
as this one. They modify the color of the note head, the stem and the beams, and the style of 
the note head, so that the voices may be easily distinguished. Voice one is set to red diamonds, 
voice two to blue triangles, voice three to green crossed circles, and voice four (not used here) to 
magenta crosses; \voiceNeutralStyle (also not used here) reverts the style back to the default. 
We shall see later how commands like these may be created by the user. See Section 4.3.1 [Vis¬ 
ibility and color of objects], page 97 and Section 4.7.2 [Using variables for layout adjustments], 
page 138. 

Polyphony does not change the relationship of notes within a \relative block. Each note is 
still calculated relative to the note immediately preceding it, or to the first note of the preceding 
chord. So in 

\relative c 1 { noteA << < noteB noteC > \\ noteD >> noteE } 

noteB is relative to noteA 

noteC is relative to noteB, not noteA; 

noteD is relative to noteB, not noteA or noteC; 

noteE is relative to noteD, not noteA. 

An alternative way, which may be clearer if the notes in the voices are widely separated, is 
to place a \relative command at the start of each voice: 
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\relative c 1 { noteA ... } 

« 

\relative c'' { < noteB noteC > ... } 

\\ 

\relative g' { noteD ... } 

» 

\relative c 1 { noteE ... } 

Let us finally analyze the voices in a more complex piece of music. Here are the notes from 
the first two bars of the second of Chopin’s Deux Nocturnes, Op 32. This example will be 
used at later stages in this and the next chapter to illustrate several techniques for producing 
notation, so please ignore for now anything in the underlying code which looks mysterious and 
concentrate just on the music and the voices - the complications will all be explained in later 
sections. 


■h> c J J.i 
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The direction of the stems is often used to indicate the continuity of two simultaneous melodic 
lines. Here the stems of the highest notes are all pointing up and the stems of the lower notes 
are all pointing down. This is the first indication that more than one voice is required. 

But the real need for multiple voices arises when notes which start at the same time have 
different durations. Look at the notes which start at beat three in the first bar. The A-flat is 
a dotted quarter note, the F is a quarter note and the D-flat is a half note. These cannot be 
written as a chord as all the notes in a chord must have the same duration. Neither can they be 
written as sequential notes, as they must start at the same time. This section of the bar requires 
three voices, and the normal practice would be to write the whole bar as three voices, as shown 
below, where we have used different note heads and colors for the three voices. Again, the code 
behind this example will be explained later, so ignore anything you do not understand. 
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Let us try to encode this music from scratch. As we shall see, this encounters some difficulties. 
We begin as we have learnt, using the << \\ >> construct to enter the music of the first bar in 
three voices: 

\new Staff \relative c' 1 { 

\key aes \major 

« 

{ c2 aes4. bes8 } \\ { <ees, c>2 des } \\ { aes'2 f4 fes } 

» I 

<c ees aes c>l | 

> 
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The stem directions are automatically assigned with the odd-numbered voices taking upward 
stems and the even-numbered voices downward ones. The stems for voices 1 and 2 are right, 
but the stems in voice 3 should go down in this particular piece of music. We can correct this by 
skipping voice three and placing the music in voice four. This is done by simply adding another 
pair of \\. 

\new Staff \relative c 11 { 

\key aes \major 
« % Voice one 

{ c2 aes4. bes8 } 

\\ % Voice two 

{ <ees, c>2 des } 

\\ 1 Omit Voice three 

\\ l Voice four 
{ aes'2 f4 fes } 

» I 

<c ees aes c>l | 

> 



We see that this fixes the stem direction, but the horizontal placement of notes is not what we 
want. LilyPond shifts the inner notes when they or their stems would collide with outer voices, 
but this is not appropriate for piano music. In other situations, the shifts LilyPond applies might 
fail to clear the collisions. LilyPond provides several ways to adjust the horizontal placing of 
notes. We are not quite ready yet to see how to correct this, so we shall leave this problem until 
a later section — see the force-hshift property in Section 4.6.2 [Fixing overlapping notation], 
page 123. 

/ \ 

Note: Lyrics, spanners (such as slurs, ties, hairpins etc.) cannot be 
created ‘across’ voices. 

v_y 


See also 

Notation Reference: Section “Multiple voices” in Notation Reference. 

3.2.2 Explicitly instantiating voices 

Voice contexts can also be created manually inside a « » block to create polyphonic music, 
using \voiceOne . . . \voiceFour to indicate the required directions of stems, slurs, etc. In 
longer scores this method is clearer, as it permits the voices to be separated and to be given 
more descriptive names. 

Specifically, the construct « \\ >> which we used in the previous section: 

\new Staff { 

\relative c' { 

« { e4 f g a } \\ { c,4 d e f } » 

> 

> 

is equivalent to 

\new Staff « 
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\new Voice = "1" { \voiceOne \relative c 1 { e4 f g a } } 
\new Voice = "2" { \voiceTwo \relative c 1 { c4 d e f } } 

» 

Both of the above would produce 



The \voiceXXX commands set the direction of stems, slurs, ties, articulations, text annota¬ 
tions, augmentation dots of dotted notes, and fingerings. \voiceOne and \voiceThree make 
these objects point upwards, while \voiceTwo and \voiceFour make them point downwards. 
These commands also generate a horizontal shift for each voice when this is required to avoid 
clashes of note heads. The command \oneVoice reverts the settings back to the normal values 
for a single voice. 

Let us see in some simple examples exactly what effect \oneVoice, \voiceOne and voiceTwo 
have on markup, ties, slurs, and dynamics: 

\relative c 1 { 

7. Default behavior or behavior after \oneVoice 
c4 d8~ d e4( f | g4 a) b-> c | 

> 



\relative c 1 { 

\voiceOne 

c4 d8~ d e4( f | g4 a) b-> c | 
\oneVoice 

c,4 d8~ d e4( f | g4 a) b-> c | 

} 



\relative c 1 { 

\voiceTwo 

c4 d8~ d e4( f | g4 a) b-> c | 
\oneVoice 

c,4 d8~ d e4( f | g4 a) b-> c | 

} 





Now let’s look at three different ways to notate the same passage of polyphonic music, each of 
which is advantageous in different circumstances, using the example from the previous section. 
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An expression that appears directly inside a « » belongs to the main voice (but, note, not 
in a << \\ >> construct). This is useful when extra voices appear while the main voice is playing. 
Here is a more correct rendition of our example. The red diamond-shaped notes demonstrate 
that the main melody is now in a single voice context, permitting a phrasing slur to be drawn 
over them. 

\new Staff \relative c' { 

\voiceOneStyle 

l This section is homophonic 
cl6"( d e f 

% Start simultaneous section of three voices 

« 

l Continue the main voice in parallel 
{ g4 f e | d2 e) I > 
l Initiate second voice 
\new Voice { 

°/ 0 Set stems, etc., down 
\voiceTwo 

r8 e4 d c8~ | c8 bl6 a b8 g~ g2 | 

} 

l Initiate third voice 
\new Voice { 

% Set stems, etc, up 

\voiceThree 

s2. | s4 b c2 | 

} 

» 

> 



More deeply nested polyphony constructs are possible, and if a voice appears only briefly 
this might be a more natural way to typeset the music: 

\new Staff \relative c' { 
cl6"( d e f 
« 

{ g4 f e I d2 e) I > 

\new Voice { 

\voiceTwo 
r8 e4 d c8~ | 

<< 

{ c8 bl6 a b8 g~ g2 I } 

\new Voice { 

\voiceThree 
s4 b c2 | 

> 

>> 

} 

» 
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> 



This method of nesting new voices briefly is useful when only small sections of the music 
are polyphonic, but when the whole staff is largely polyphonic it can be clearer to use multiple 
voices throughout, using spacing notes to step over sections where the voice is silent, as here: 

\new Staff \relative c' « 

7» Initiate first voice 
\new Voice { 

\voiceOne 

cl6~( d e f g4 f e | d2 e) | 

> 

°l Initiate second voice 
\new Voice { 

7. Set stems, etc, down 
\voiceTwo 

s4 r8 e4 d c8~ I c8 bl6 a b8 g~ g2 | 

> 

l Initiate third voice 
\new Voice { 

7, Set stems, etc, up 

\voiceThree 

si I s4 b c2 | 

> 



Note columns 

Closely spaced notes in a chord, or notes occurring at the same time in different voices, are 
arranged in two, occasionally more, columns to prevent the note heads overlapping. These are 
called note columns. There are separate columns for each voice, and the currently specified 
voice-dependent shift is applied to the note column if there would otherwise be a collision. This 
can be seen in the example above. In bar 2 the C in voice two is shifted to the right relative to 
the D in voice one, and in the final chord the C in voice three is also shifted to the right relative 
to the other notes. 

The \shiftOn, \shiftOnn, \shiftOnnn, and \shiftOff commands specify the degree to 
which notes and chords of the voice should be shifted if a collision would otherwise occur. By 
default, the outer voices (normally voices one and two) have \shiftOff specified, while the 
inner voices (three and four) have \shiftOn specified. When a shift is applied, voices one and 
three are shifted to the right and voices two and four to the left. 

\shiftOnn and \shiftOnnn define further shift levels which may be specified temporarily to 
resolve collisions in complex situations - see Section 4.6.3 [Real music example], page 128. 
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A note column can contain just one note (or chord) from a voice with stems up and one note 
(or chord) from a voice with stems down. If notes from two voices which have their stems in the 
same direction are placed at the same position and both voices have no shift or the same shift 
specified, the error message “Too many clashing note columns” will be produced. 

See also 

Learning Manual: Section 4.6.1 [Moving objects], page 120. 

Notation Reference: Section “Multiple voices” in Notation Reference. 

3.2.3 Voices and vocals 

Vocal music presents a special difficulty: we need to combine two expressions - notes and lyrics. 

You have already seen the \addlyrics-Q command, which handles simple scores well. How¬ 
ever, this technique is quite limited. For more complex music, you must introduce the lyrics in a 
Lyrics context using \new Lyrics and explicitly link the lyrics to the notes with \lyricsto-Q, 
using the name assigned to the Voice. 

« 

\new Voice = "one" { 

\relative c 11 { 

\autoBeamOff 
\time 2/4 

c4 b8. al6 | g4. f8 | e4 d | c2 | 

} 

> 

\new Lyrics \lyricsto "one" { 

No more let | sins and I sor — rows I grow. I 

> 

» 





£ 


£ 


No more let sins and sor rows grow. 


Note that the lyrics must be linked to a Voice context, not a Staff context. This is a case 
where it is necessary to create Staff and Voice contexts explicitly. 

The automatic beaming which LilyPond uses by default works well for instrumental music, 
but not so well for music with lyrics, where beaming is either not required at all or is used to 
indicate melismata in the lyrics. In the example above we use the command \autoBeamOf f to 
turn off the automatic beaming. 

Let us reuse the earlier example from Judas Maccabaeus to illustrate this more flexible tech¬ 
nique. We first recast it to use variables so the music and lyrics can be separated from the staff 
structure. We also introduce a ChoirStaff bracket. The lyrics themselves must be introduced 
with \lyricmode to ensure they are interpreted as lyrics rather than music. 

global = { \key f \major \time 6/8 \partial 8 } 

SopOneMusic = \relative c 11 { 

c8 | c8([ bes)] a a([ g)] f | f'4. b, | c4.~ c4 

> 

SopOneLyrics = \lyricmode { 

Let | flee — cy flocks the | hills a — dorn, 

> 

















Chapter 3: Fundamental concepts 


56 


SopTwoMusic = \relative c' { 

r8 | r4. r4 c8 | a'8([ g)] f f([ e)] d | e8([ d)] c bes' 

} 

SopTwoLyrics = \lyricmode { 

Let I flee — cy flocks the | hills a — dorn, 

} 

\score { 

\new ChoirStaff « 

\new Staff << 

\new Voice = "SopOne" { 

\global 

\SopOneMusic 

> 

\new Lyrics \lyricsto "SopOne" { 

\SopOneLyrics 

> 

>> 

\new Staff << 

\new Voice = "SopTwo" { 

\global 

\SopTwoMusic 

> 

\new Lyrics \lyricsto "SopTwo" { 

\SopTwoLyrics 

> 

>> 

» 

> 



Let flee cy flocks the hills adorn, 


This is the basic structure of all vocal scores. More staves may be added as required, more 
voices may be added to the staves, more verses may be added to the lyrics, and the variables 
containing the music can easily be placed in separate files should they become too long. 

Here is an example of the first line of a hymn with four verses, set for SATB. In this case 
the words for all four parts are the same. Note how we use variables to separate the music 
notation and words from the staff structure. See too how a variable, which we have chosen 
to call ‘keyTime’, is used to hold several commands for use within the two staves. In other 
examples this is often called ‘global’. 

keyTime = { \key c \major \time 4/4 \partial 4 } 

SopMusic = \relative c' { c4 | e4. e8 g4 g | a4 a g } 

AltoMusic = \relative c' { c4 | c4. c8 e4 e I f4 f e } 

TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 } 
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BassMusic = \relative c { c4 | c4. c8 c4 c I f8 g a b c4 } 


VerseOne = 
Myricmode 
VerseTwo = 
Myricmode 
VerseThree = 
Myricmode 
VerseFour = 
Myricmode 


{ E — I ter — nal fa — ther, | strong to save, } 
{ 0 I Christ, whose voice the | wa — ters heard, } 
{ 0 | Ho — ly Spi — rit, | who didst brood } 

{ 0 I Tri — ni — ty of | love and pow'r } 


\score { 

\new ChoirStaff « 

\new Staff « 

\clef "treble" 

\new Voice = "Sop" { \voiceOne \keyTime \SopMusic } 

\new Voice = "Alto" { \voiceTwo \AltoMusic } 

\new Lyrics Myricsto "Sop" { WerseOne } 

\new Lyrics Myricsto "Sop" { WerseTwo } 

\new Lyrics Myricsto "Sop" { WerseThree } 

\new Lyrics Myricsto "Sop" { WerseFour } 

>> 

\new Staff « 

\clef "bass" 

\new Voice = "Tenor" { \voiceOne \keyTime MenorMusic } 

\new Voice = "Bass" { \voiceTwo \BassMusic } 

>> 

» 

> 






ft T f t 


rr 

E - ter - nal fa-ther, strong to save, 
O Christ, whose voice the wa - ters heard, 
O Ho - ly Spi-rit, who didst brood 
O Tri - ni - ty of love and pow'r 




$ 


J. J> * 





See also 

Notation Reference: Section “Vocal music” in Notation Reference. 


3.3 Contexts and engravers 

Contexts and engravers have been mentioned informally in earlier sections; we now must look 
at these concepts in more detail, as they are important in the fine-tuning of LilyPond output. 
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3.3.1 Contexts explained 

When music is printed, many notational elements which do not appear explicitly in the input 
file must be added to the output. For example, compare the input and output of the following 
example: 

cis4 cis2. | a4 a2. I 



The input is rather sparse, but in the output, bar lines, accidentals, clef, and time signature 
have been added. When LilyPond interprets the input the musical information is parsed from left 
to right, similar to the way a performer reads the score. While reading the input, the program 
remembers where measure boundaries are, and which pitches require explicit accidentals. This 
information must be held on several levels. For example, an accidental affects only a single staff, 
while a bar line must be synchronized across the entire score. 

Within LilyPond, these rules and bits of information are grouped in Contexts. We have 
already introduced the Voice context. Others are the Staff and Score contexts. Contexts are 
hierarchical to reflect the hierarchical nature of a musical score. For example: a Staff context 
can contain many Voice contexts, and a Score context can contain many Staff contexts. 



Each context has the responsibility for enforcing some notation rules, creating some nota¬ 
tion objects and maintaining the associated properties. For example, the Voice context may 
introduce an accidental and then the Staff context maintains the rule to show or suppress the 
accidental for the remainder of the measure. 

As another example, the synchronization of bar lines is, by default, handled in the Score 
context. However, in some music we may not want the bar lines to be synchronized - consider 
a polymetric score in 4/4 and 3/4 time. In such cases, we must modify the default settings of 
the Score and Staff contexts. 

For very simple scores, contexts are created implicitly, and you need not be aware of them. 
For larger pieces, such as anything with more than one staff, they must be created explicitly 
to make sure that you get as many staves as you need, and that they are in the correct order. 
For typesetting pieces with specialized notation, it is usual to modify existing, or even to define 
totally new, contexts. 

In addition to the Score, Staff and Voice contexts there are contexts which fit between the 
score and staff levels to control staff groups, such as the PianoStaf f and ChoirStaf f contexts. 
There are also alternative staff and voice contexts, and contexts for lyrics, percussion, fret 
boards, figured bass, etc. 

The names of all context types are formed from one or more words, each word being cap¬ 
italized and joined immediately to the preceding word with no hyphen or underscore, e.g., 

GregorianTranscriptionStaff. 

See also 

Notation Reference: Section “Contexts explained” in Notation Reference. 
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3.3.2 Creating contexts 

In an input file a score block, introduced with a \score command, contains a single music ex¬ 
pression and an associated output definition (either a \layout or a \midi block). The Score 
context is usually left to be created automatically when the interpretation of that music expres¬ 
sion starts. 

For scores with only one voice and one staff, the Voice and Staff contexts may also be 
left to be created automatically, but for more complex scores it is necessary to create them by 
hand. The simplest command that does this is \new. It is prepended to a music expression, for 
example 

\new type music-expression 

where type is a context name (like Staff or Voice). This command creates a new context, and 
starts interpreting the music-expression within that context. 

/ \ 

Note: \new Score should not be used as the essential top-level Score 
context is created automatically when the music expression within the 
\score block is interpreted. Score-wide default values of context prop¬ 
erties can be changed within the \layout block. See Section 3.3.4 [Mod¬ 
ifying context properties], page 61 

v_ 

You have seen many practical examples which created new Staff and Voice contexts in 
earlier sections, but to remind you how these commands are used in practice, here’s an annotated 
real-music example: 

\score { % start of single compound music expression 

« 1 start of simultaneous staves section 

\time 2/4 

\new Staff { % create RH staff 

\clef "treble" 

\key g \minor 

\new Voice { % create voice for RH notes 

\relative c 11 { % start of RH notes 

d4 eesl6 c8. | 
d4 eesl6 c8. | 

} 7. end of RH notes 

} 7. end of RH voice 

} 7o end of RH staff 

\new Staff « 7o create LH staff; needs two simultaneous voices 
\clef "bass" 

\key g \minor 

\new Voice { 7o create LH voice one 
\voiceOne 

\relative g { °/ 0 start of LH voice one notes 

g8 <bes d> ees, <g c> | 
g8 <bes d> ees, <g c> | 

} 7. end of LH voice one notes 

} 7o end of LH voice one 
\new Voice { 7o create LH voice two 
\voiceTwo 

\relative g { 7o start of LH voice two notes 
g4 ees | 
g4 ees | 
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} 7, end of LH voice two notes 

} 7o end of LH voice two 
>> 7 0 end of LH staff 

» % end of simultaneous staves section 

} 7. end of single compound music expression 


in 


m 






(Note how all the statements which open a block with either a curly bracket, {, or double 
angle brackets, «, are indented by two further spaces, and the corresponding closing bracket 
is indented by exactly the same amount. While this is not required, following this practice 
will greatly reduce the number of ‘unmatched bracket’ errors, and is strongly recommended. It 
enables the structure of the music to be seen at a glance, and any unmatched brackets will be 
obvious. Note too how the LH staff is created using double angle brackets because it requires two 
voices for its music, whereas the RH staff is created with a single music expression surrounded 
by curly brackets because it requires only one voice.) 

The \new command may also give an identifying name to the context to distinguish it from 
other contexts of the same type, 

\new type = id music-expression 

Note the distinction between the name of the context type, Staff, Voice, etc, and the 
identifying name of a particular instance of that type, which can be any sequence of letters 
invented by the user. Digits and spaces can also be used in the identifying name, but then it 
has to be placed in quotes, i.e. \new Staff = "MyStaff 1" music-expression. The identifying 
name is used to refer back to that particular instance of a context. We saw this in use in the 
section on lyrics, see Section 3.2.3 [Voices and vocals], page 55. 

See also 

Notation Reference: Section “Creating and referencing contexts’’ in Notation Reference. 

3.3.3 Engravers explained 

Every mark on the printed output of a score produced by LilyPond is produced by an Engraver. 
Thus there is an engraver to print staves, one to print note heads, one for stems, one for beams, 
etc, etc. In total there are over 120 such engravers! Fortunately, for most scores it is not 
necessary to know about more than a few, and for simple scores you do not need to know about 
any. 

Engravers live and operate in Contexts. Engravers such as the Metronome_mark_engraver, 
whose action and output apply to the score as a whole, operate in the highest level context - 
the Score context. 

The Clef_engraver and Key_engraver are to be found in every Staff Context, as different 
staves may require different clefs and keys. 

The Note_heads_engraver and Stem_engraver live in every Voice context, the lowest level 
context of all. 

Each engraver processes the particular objects associated with its function, and maintains 
the properties that relate to that function. These properties, like the properties associated with 
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contexts, may be modified to change the operation of the engraver or the appearance of those 
elements in the printed score. 

Engravers all have compound names formed from words which describe their function. Just 
the first word is capitalized, and the remainder are joined to it with underscores. Thus the 
Staff_symbol_engraver is responsible for creating the lines of the staff, the Clef_engraver 
determines and sets the pitch reference point on the staff by drawing a clef symbol. 

Here are some of the most common engravers together with their function. You will see it is 
usually easy to guess the function from the name, or vice versa. 


Engraver 

AccidentaLengraver 

Beam.engraver 

CleLengraver 

Completion_heads_engraver 
Dynamic _ engraver 
Forbid_line_break_engraver 
Key_engraver 

Metronome_mark_engraver 

Note_heads_engraver 

Rest.engraver 

Staff-symbol_engraver 

Stem_engraver 

Time _ signature .engraver 


Function 

Makes accidentals, cautionary and suggested accidentals 
Engraves beams 
Engraves clefs 

Splits notes which cross bar lines 

Creates hairpins and dynamic texts 

Prevents line breaks if a musical element is still active 

Creates the key signature 

Engraves metronome marking 

Engraves note heads 

Engraves rests 

Engraves the five (by default) lines of the staff 
Creates stems and single-stem tremolos 
Creates time signatures 


We shall see later how the output of LilyPond can be changed by modifying the action of 
Engravers. 

See also 

Internals reference: Section “Engravers and Performers” in Internals Reference. 

3.3.4 Modifying context properties 

Contexts are responsible for holding the values of a number of context properties. Many of them 
can be changed to influence the interpretation of the input and so change the appearance of the 
output. They are changed by the \set command. This takes the form 
\set ContextName.propertyName = #value 

Where the ContextName is usually Score, Staff or Voice. It may be omitted, in which case 
the current context (typically Voice) is assumed. 

The names of context properties consist of words joined together with no hyphens or under¬ 
scores, all except the first having a capital letter. Here are a few examples of some commonly 
used ones. There are many more. 


propertyName 

Type 

Function 

Example 

Value 

extraNatural 

Boolean 

If true, set extra natural signs before 
accidentals 

ct 

4* 

l-h 

currentBarNumber 

Integer 

Set the current bar number 

50 

doubleSlurs 

Boolean 

If true, print slurs both above and below 
notes 

=8= 

c+ 

# 

l-h 

instrumentName 

Text 

Set the name to be placed at the start of 
the staff 

"Cello I 
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fontSize Real Increase or decrease the font size 2.4 

stanza Text Set the text to print before the start of "2" 

a verse 

where a Boolean is either True (#t) or False (#f), an Integer is a positive whole number, a Real 
is a positive or negative decimal number, and text is enclosed in double apostrophes. Note the 
occurrence of hash signs, (#), in two different places - as part of the Boolean value before the t 
or f, and before value in the \set statement. So when a Boolean is being entered you need to 
code two hash signs, e.g., ##t. 

Before we can set any of these properties we need to know in which context they operate. 
Sometimes this is obvious, but occasionally it can be tricky. If the wrong context is specified, 
no error message is produced, but the expected action will not take place. For example, the 
instrumentName clearly lives in the Staff context, since it is the staff that is to be named. In 
this example the first staff is labeled, but not the second, because we omitted the context name. 
« 

\new Staff \relative c 11 { 

\set Staff.instrumentName = #"Soprano" 
c2 c 

> 

\new Staff \relative c' { 

\set instrumentName = #"Alto" % Wrong! 
d2 d 

> 

» 


Soprano 



Remember the default context name is Voice, so the second \set command set the property 
instrumentName in the Voice context to “Alto”, but as LilyPond does not look for any such 
property in the Voice context, no further action took place. This is not an error, and no error 
message is logged in the log file. 

Similarly, if the property name is mis-spelt no error message is produced, and clearly the 
expected action cannot be performed. In fact, you can set any (fictitious) ‘property’ using any 
name you like in any context that exists by using the \set command. But if the name is not 
known to LilyPond it will not cause any action to be taken. Some text editors with special 
support for LilyPond input files document property names with bullets when you hover them 
with the mouse, like JEdit with LilyPondTool, or highlight unknown property names differently, 
like ConTEXT. If you do not use an editor with such features, it is recommended to check the 
property name in the Internals Reference: see Section “Tunable context properties” in Internals 
Reference, or Section “Contexts” in Internals Reference. 

The instrumentName property will take effect only if it is set in the Staff context, but some 
properties can be set in more than one context. For example, the property extraNatural is 
by default set to ##t (true) for all staves. If it is set to ##f (false) in one particular Staff 
context it applies just to the accidentals on that staff. If it is set to false in the Score context 
it applies to all staves. 

So this turns off extra naturals in one staff: 
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<< 

\new Staff \relative c 11 { 
aeses2 aes 

> 

\new Staff \relative c 1 ' { 

\set Staff.extraNatural = ##f 
aeses2 aes 

> 

>> 



and this turns them off in all staves: 
<< 


\new Staff \relative c 1 ' { 
aeses2 aes 

> 

\new Staff \relative c 11 { 

\set Score.extraNatural = ##f 
aeses2 aes 


> 


>> 



As another example, if clefTransposition is set in the Score context this immediately 
changes the value of the transposition in all current staves and sets a new default value which 
will be applied to all staves. 

The opposite command, \unset, effectively removes the property from the context, which 
causes most properties to revert to their default value. Usually \unset is not required as a new 
\set command will achieve what is wanted. 

The \set and \unset commands can appear anywhere in the input file and will take effect 
from the time they are encountered until the end of the score or until the property is \set or 
\unset again. Let’s try changing the font size, which affects the size of the note heads (among 
other things) several times. The change is from the default value, not the most recently set 
value. 

c4 d 

% make note heads smaller 
\set fontSize = #-4 
e4 f | 

% make note heads larger 
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\set fontSize = #2.5 
g4 a 

l return to default size 
\unset fontSize 
b4 c I 
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We have now seen how to set the values of several different types of property. Note that 
integers and numbers are always preceded by a hash sign, #, while a true or false value is 
specified by ##t and ##f , with two hash signs. A text property should be enclosed in double 
quotation signs, as above, although we shall see later that text can actually be specified in a 
much more general way by using the very powerful \markup command. 

Setting context properties with \with 

The default value of context properties may be set at the time the context is created. Sometimes 
this is a clearer way of setting a property value if it is to remain fixed for the duration of the 
context. When a context is created with a \new command it may be followed immediately by 
a \with { . . . } block in which the default property values are set. For example, if we wish to 
suppress the printing of extra naturals for the duration of a staff we would write: 

\new Staff \with { extraNatural = ##f } 
like this: 

<< 

\new Staff { 

\relative c 11 { 

gisis4 gis aeses aes 

} 

> 

\new Staff \with { extraNatural = ##f } { 

\relative c 11 { 

gisis4 gis aeses aes 

} 

> 

» 



Properties set in this way may still be changed dynamically using \set and returned to the 
default value set in the \with block with \unset. 

So if the fontSize property is set in a \with clause it sets the default value of the font 
size. If it is later changed with \set, this new default value may be restored with the \unset 
fontSize command. 
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Setting context properties with \context 

The values of context properties may be set in all contexts of a particular type, such as all 
Staff contexts, with a single command. The context type is identified by using its type name, 
like Staff, prefixed by a back-slash: \Staff . The statement which sets the property value is 
the same as that in a \with block, introduced above. It is placed in a \context block within 
a \layout block. Each \context block will affect all contexts of the type specified throughout 
the \score or \book block in which the \layout block appears. Here is an example to show 
the format: 

\score { 

\new Staff { 

\relative c 11 { 
cisis4 e d cis 

} 

> 

\layout { 

\context { 

\Staff 

extraNatural = ##t 

} 

> 

> 



If the property override is to be applied to all staves within the score: 


\score { 
<< 


\new Staff { 

\relative c 11 { 
gisis4 gis aeses 

> 

} 

\new Staff { 

\relative c 11 { 
gisis4 gis aeses 

> 

} 


aes 


aes 


» 

May out { 

\context { 

\Score extraNatural = ##f 

} 

> 
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Context properties set in this way may be overridden for particular instances of contexts by 
statements in a \with block, and by \set commands embedded in music statements. 

See also 

Notation Reference: Section “Changing context default settings” in Notation Reference. 
Section “The set command” in Notation Reference. 

Internals Reference: Section “Contexts” in Internals Reference, Section “Tunable context 
properties” in Internals Reference. 

3.3.5 Adding and removing engravers 

We have seen that contexts each contain several engravers, each of which is responsible for 
producing a particular part of the output, like bar lines, staves, note heads, stems, etc. If an 
engraver is removed from a context, it can no longer produce its output. This is a crude way of 
modifying the output, but it can sometimes be useful. 

Changing a single context 

To remove an engraver from a single context we use the \with command placed immediately 
after the context creation command, as in the previous section. 

As an illustration, let’s repeat an example from the previous section with the staff lines 
removed. Remember that the staff lines are produced by the Staff_symbol_engraver. 

\new Staff \with { 

\remove "Staff_symbol_engraver" 

> 

\relative c 1 { 
c4 d 

\set fontSize = #-4 % make note heads smaller 

e4 f I 

\set fontSize = #2.5 % make note heads larger 

fontSize % return to default size 


jjjJ J J rr 

Engravers can also be added to individual contexts. The command to do this is 
\consists Engraver_name, 

placed inside a \with block. Some vocal scores have an ambitus placed at the beginning of a 
staff to indicate the range of notes in that staff - see Section “ambitus” in Music Glossary. The 
ambitus is produced by the Ambitus_engraver, which is not normally included in any context. 
If we add it to the Voice context, it calculates the range from that voice only: 

\new Staff « 

\new Voice \with { 

\consists "Ambitus_engraver" 


g4 a 
\unset 
b4 c I 
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> { 

\relative c 11 { 
\voiceOne 
c4 a b g 

} 

> 

\new Voice { 

\relative c 1 { 
\voiceTwo 
c4 e d f 

} 

> 



but if we add the ambitus engraver to the Staff context, it calculates the range from all the 
notes in all the voices on that staff: 

\new Staff \with { 

\consists "Ambitus_engraver" 

> 

<< 

\new Voice { 

\relative c 11 { 

\voiceOne 
c4 a b g 

} 

> 

\new Voice { 

\relative c' { 

\voiceTwo 
c4 e d f 

} 

> 

» 



Changing all contexts of the same type 

The examples above show how to remove or add engravers to individual contexts. It is also 
possible to remove or add engravers to every context of a specific type by placing the commands 
in the appropriate context in a \layout block. For example, if we wanted to show an ambitus 
for every staff in a four-staff score, we could write 

\score { 

« 


\new Staff { 
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\relative c 11 { 
c4 a b g 

> 

} 

\new Staff { 

\relative c' { 
c4 a b g 

> 

} 

\new Staff { 

\clef "G_8" 

\relative c' { 
c4 a b g 

> 

} 

\new Staff { 

\clef "bass" 

\relative c { 
c4 a b g 

> 

} 

» 

May out { 

\context { 

\Staff 

\consists "Ambitus_engraver" 

} 

> 

> 



The values of context properties may also be set for all contexts of a particular type by including 
the \set command in a \ context block in the same way. 

See also 

Notation Reference: Section “Modifying context plug-ins” in Notation Reference, Section 
“Changing context default settings” in Notation Reference. 
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Known issues and warnings 

The Stem_engraver and Beam_engraver attach their objects to note heads. If the 
Note_heads_engraver is removed no note heads are produced and therefore no stems or beams 
are created either. 

3.4 Extending the templates 

You’ve read the tutorial, you know how to write music, you understand the fundamental con¬ 
cepts. But how can you get the staves that you want? Well, you can find lots of templates (see 
Appendix A [Templates], page 146) which may give you a start. But what if you want something 
that isn’t covered there? Read on. 

3.4.1 Soprano and cello 

Start off with the template that seems closest to what you want to end up with. Let’s say that 
you want to write something for soprano and cello. In this case, we would start with the ‘Notes 
and lyrics’ template (for the soprano part). 

\version "2.18.2" 

melody = \relative c 1 { 

\clef "treble" 

\key c \major 
\time 4/4 
a4 b c d 

> 

text = \lyricmode { 

Aaa Bee Cee Dee 

> 

\score { 

« 

\new Voice = "one" { 

\autoBeamOff 
\melody 

} 

\new Lyrics \lyricsto "one" \text 

» 

\layout { } 

\midi { } 

> 

Now we want to add a cello part. Let’s look at the ‘Notes only’ example: 

\version "2.18.2" 

melody = \relative c 1 { 

\clef "treble" 

\key c \major 
\time 4/4 
a4 b c d 

> 


\score { 
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\new Staff \melody 
\layout { } 

\midi { } 

> 

We don’t need two \version commands. We’ll need the melody section. We don’t want two 
\score sections - if we had two \scores, we’d get the two parts separately. We want them 
together, as a duet. Within the \score section, we don’t need two \layout or \midi. 

If we simply cut and paste the melody section, we would end up with two melody definitions. 
This would not generate an error, but the second one would be used for both melodies. So 
let’s rename them to make them distinct. We’ll call the section for the soprano sopranoMusic 
and the section for the cello celloMusic. While we’re doing this, let’s rename text to be 
sopranoLyrics. Remember to rename both instances of all these names - both the initial 
definition (the melody = \relative c' { part) and the name’s use (in the \score section). 

While we’re doing this, let’s change the cello part’s staff - celli normally use bass clef. We’ll 
also give the cello some different notes. 

\version "2.18.2" 

sopranoMusic = \relative c 1 { 

\clef "treble" 

\key c \major 
\time 4/4 
a4 b c d 

> 

sopranoLyrics = Myricmode { 

Aaa Bee Cee Dee 

> 

celloMusic = \relative c { 

\clef "bass" 

\key c \major 
\time 4/4 
d4 g fis8 e d4 

> 

\score { 

« 

\new Voice = "one" { 

\autoBeamOff 
\sopranoMusic 

} 

\new Lyrics Myricsto "one" \sopranoLyrics 

» 

\layout { } 

\midi { } 

> 

This is looking promising, but the cello part won’t appear in the score - we haven’t used it 
in the \score section. If we want the cello part to appear under the soprano part, we need to 
add 


\new Staff \celloMusic 
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underneath the soprano stuff. We also need to add << and » around the music - that tells 
LilyPond that there’s more than one thing (in this case, two Staves) happening at once. The 
\score looks like this now: 

\score { 

« 

« 

\new Voice = "one" { 

\autoBeamOff 
\sopranoMusic 

} 

\new Lyrics \lyricsto "one" \sopranoLyrics 

» 

\new Staff \celloMusic 

» 

\layout { } 

\midi { } 

> 

This looks a bit messy; the indentation is messed up now. That is easily fixed. Here’s the 
complete soprano and cello template. 

\version "2.18.2" 

sopranoMusic = \relative c 1 { 

\clef "treble" 

\key c \major 
\time 4/4 
a4 b c d 


sopranoLyrics = Myricmode { 

Aaa Bee Cee Dee 

} 

celloMusic = \relative c { 

\clef "bass" 

\key c \major 
\time 4/4 
d4 g fis8 e d4 

> 

\score { 

<< 

<< 

\new Voice = "one" { 

\autoBeamOff 
\sopranoMusic 

> 

\new Lyrics Myricsto "one" \sopranoLyrics 

>> 

\new Staff \celloMusic 

» 

\layout { } 

\midi { } 
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> 



See also 

The starting templates can be found in the ‘Templates’ appendix, see Section A.l [Single 
staff templates], page 146. 

3.4.2 Four-part SATB vocal score 

Most vocal scores of music written for four-part mixed choir with orchestral accompaniment such 
as Mendelssohn’s Elijah or Handel’s Messiah have the choral music and words on four staves, 
one for each of SATB, with a piano reduction of the orchestral accompaniment underneath. 
Here’s an example from Handel’s Messiah: 



None of the templates provides this layout exactly. The nearest is Section A.4.2 [SATB vocal 
score and automatic piano reduction], page 157 - but we need to change the layout and add a 
piano accompaniment which is not derived automatically from the vocal parts. The variables 
holding the music and words for the vocal parts are fine, but we shall need to add variables for 
the piano reduction. 

The order in which the contexts appear in the ChoirStaff of the template do not correspond 
with the order in the vocal score shown above. We need to rearrange them so there are four 
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staves with the words written directly underneath the notes for each part. All the voices should 
be \voiceOne, which is the default, so the \voiceXXX commands should be removed. We also 
need to specify the tenor clef for the tenors. The way in which lyrics are specified in the template 
has not yet been encountered so we need to use the method with which we are familiar. We 
should also add the names of each staff. 

Doing this gives for our ChoirStaff: 

\new ChoirStaff « 

\new Staff = "sopranos" << 

\set Staff.instrumentName = #"Soprano" 

\new Voice = "sopranos" { 

\global 

\sopranoMusic 

} 

» 

\new Lyrics \lyricsto "sopranos" { 

\sopranoWords 

> 

\new Staff = "altos" « 

\set Staff.instrumentName = #"Alto" 

\new Voice = "altos" { 

\global 

\altoMusic 

} 

» 

\new Lyrics \lyricsto "altos" { 

\altoWords 

> 

\new Staff = "tenors" « 

\set Staff.instrumentName = #"Tenor" 

\new Voice = "tenors" { 

\global 

\tenorMusic 

} 

» 

\new Lyrics \lyricsto "tenors" { 

\tenorWords 

> 

\new Staff = "basses" « 

\set Staff.instrumentName = #"Bass" 

\new Voice = "basses" { 

\global 

\bassMusic 

} 

» 

\new Lyrics \lyricsto "basses" { 

\bassWords 

> 

» % end ChoirStaff 

Next we must work out the piano part. This is easy - we just pull out the piano part from 
the ‘Solo piano’ template: 

\new PianoStaff « 
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\set PianoStaff.instrumentName = #"Piano " 

\new Staff = "upper" \upper 
\new Staff = "lower" Mower 

» 

and add the variable definitions for upper and lower. 

The ChoirStafF and PianoStaff must be combined using angle brackets as we want them to 
be stacked one above the other: 

« 7, combine ChoirStaff and PianoStaff one above the other 

\new ChoirStaff « 

\new Staff = "sopranos" << 

\new Voice = "sopranos" { 

\global 

\sopranoMusic 

> 

>> 

\new Lyrics Myricsto "sopranos" { 

\sopranoWords 

} 

\new Staff = "altos" « 

\new Voice = "altos" { 

\global 

\altoMusic 

> 

>> 

\new Lyrics Myricsto "altos" { 

\altoWords 

} 

\new Staff = "tenors" << 

\clef "G_8" y o tenor clef 
\new Voice = "tenors" { 

\global 

\tenorMusic 

> 

>> 

\new Lyrics Myricsto "tenors" { 

\tenorWords 

} 

\new Staff = "basses" << 

\clef "bass" 

\new Voice = "basses" { 

\global 

\bassMusic 

> 

>> 

\new Lyrics Myricsto "basses" { 

\bassWords 

} 

» */. end ChoirStaff 

\new PianoStaff « 

\set PianoStaff.instrumentName = #"Piano" 
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\new Staff = "upper" \upper 
\new Staff = "lower" Mower 

» 

» 

Combining all these together and adding the music for the three bars of the example above 
gives: 

\version "2.18.2" 

global = { \key d \major \time 4/4 } 
sopranoMusic = \relative c 11 { 

\clef "treble" 

r4 d2 a4 | d4. d8 a2 | cis4 d cis2 | 

} 

sopranoWords = \lyricmode { 

Wor — thy I is the lamb | that was slain | 

} 

altoMusic = \relative a' { 

\clef "treble" 

r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 | 

} 

altoWords = \sopranoWords 
tenorMusic = \relative c' { 

\clef "G_8" 

r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 | 

> 

tenorWords = \sopranoWords 
bassMusic = \relative c 1 { 

\clef "bass" 

r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 | 

> 

bassWords = \sopranoWords 
upper = \relative a' { 

\clef "treble" 

\global 

r4 <a d fis>2 <a e 1 a>4 | 

<d fis d'>4. <d fis d’>8 <a d a'>2 | 

<g cis g'>4 <a d fis> <a cis e>2 I 

} 

lower = \relative c, { 

\clef "bass" 

\global 

<d d'>4 <d d'>2 <cis cis'>4 | 

<b b'>4. <b' b'>8 <fis fis’>2 | 

<e e'>4 <d d'> <a' a'>2 | 

> 

\score { 

<< */. combine ChoirStaff and PianoStaff in parallel 

\new ChoirStaff << 

\new Staff = "sopranos" << 

\set Staff.instrumentName = #"Soprano" 

\new Voice = "sopranos" { 
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\global 

\sopranoMusic 

> 

>> 

\new Lyrics \lyricsto "sopranos" { 
\sopranoWords 

> 

\new Staff = "altos" << 

\set Staff.instrumentName = #"Alto" 

\new Voice = "altos" { 

\global 

\altoMusic 

} 

>> 

\new Lyrics \lyricsto "altos" { 

\altoWords 

> 

\new Staff = "tenors" << 

\set Staff.instrumentName = #"Tenor" 

\new Voice = "tenors" { 

\global 

\tenorMusic 

> 

>> 

\new Lyrics \lyricsto "tenors" { 

\tenorWords 

> 

\new Staff = "basses" << 

\set Staff.instrumentName = #"Bass" 

\new Voice = "basses" { 

\global 

\bassMusic 

> 

>> 

\new Lyrics \lyricsto "basses" { 

\bassWords 

> 

>> */. end ChoirStaff 

\new PianoStaff << 

\set PianoStaff.instrumentName = #"Piano " 
\new Staff = "upper" \upper 
\new Staff = "lower" \lower 

>> 

» 

} 
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3.4.3 Building a score from scratch 

After gaining some facility with writing LilyPond code, you may find that it is easier to build a 
score from scratch rather than modifying one of the templates. You can also develop your own 
style this way to suit the sort of music you like. Let’s see how to put together the score for an 
organ prelude as an example. 

We begin with a header section. Here go the title, name of composer, etc, then come any 
variable definitions, and finally the score block. Let’s start with these in outline and fill in the 
details later. 

We’ll use the first two bars of Bach’s prelude based on Jesu, meine Freude which is written 
for two manuals and pedal organ. You can see these two bars of music at the bottom of this 
section. The top manual part has two voices, the lower and pedal organ one each. So we need 
four music definitions and one to define the time signature and key: 

\version "2.18.2" 

\header { 

title = "Jesu, meine Freude" 
composer = "J S Bach" 

} 

keyTime = { \key c \minor \time 4/4 } 

ManualOneVoiceOneMusic = { si } 

ManualOneVoiceTwoMusic = { si } 

ManualTwoMusic = { si } 

PedalOrganMusic = { si } 

\score { 

> 

For now we’ve just used a spacer note, si, instead of the real music. We’ll add that later. 

Next let’s see what should go in the score block. We simply mirror the staff structure we 
want. Organ music is usually written on three staves, one for each manual and one for the 
pedals. The manual staves should be bracketed together, so we need to use a PianoStaff for 
them. The first manual part needs two voices and the second manual part just one. 
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\new PianoStaff « 

\new Staff = "ManualOne" << 

\new Voice { 

\ManualQneVoiceOneMusic 

} 

\new Voice { 

\ManualOneVoiceTwoMusic 

} 

» % end ManualOne Staff context 

\new Staff = "ManualTwo" << 

\new Voice { 

\MamialTwoMusic 

} 

» % end ManualTwo Staff context 

» 7, end PianoStaff context 

Next we need to add a staff for the pedal organ. This goes underneath the PianoStaff, but 
it must be simultaneous with it, so we need angle brackets around the two. Missing these out 
would generate an error in the log file. It’s a common mistake which you’ll make sooner or 
later! Try copying the final example at the end of this section, remove these angle brackets, and 
compile it to see what errors it generates. 

« % PianoStaff and Pedal Staff must be simultaneous 

\new PianoStaff « 

\new Staff = "ManualOne" << 

\new Voice { 

\ManualOneVoiceOneMusic 

> 

\new Voice { 

\ManualOneVoiceTwoMusic 

> 

>> y o end ManualOne Staff context 
\new Staff = "ManualTwo" « 

\new Voice { 

\ManualTwoMusic 

> 

>> 7. end ManualTwo Staff context 

» 7o end PianoStaff context 
\new Staff = "PedalOrgan" << 

\new Voice { 

\PedalOrganMusic 

} 

» 

» 

It is not necessary to use the simultaneous construct « ... >> for the manual two staff 
and the pedal organ staff, since they contain only one music expression, but it does no harm, 
and always using angle brackets after \new Staff is a good habit to cultivate in case there are 
multiple voices. The opposite is true for Voices: these should habitually be followed by braces 
{ ... } in case your music is coded in several variables which need to run consecutively. 

Let’s add this structure to the score block, and adjust the indenting. We also add the 
appropriate clefs, ensure stems, ties and slurs in each voice on the upper staff point to the right 
direction with \voiceOne and \voiceTwo, and enter the key and time signature to each staff 
using our predefined variable, \keyTime. 
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\score { 

« */. PianoStaff and Pedal Staff must be simultaneous 

\new PianoStaff << 

\new Staff = "ManualOne" « 

\keyTime % set key and time signature 
\clef "treble" 

\new Voice { 

\voiceOne 

\ManualOneVoiceOneMusic 

> 

\new Voice { 

\voiceTwo 

\ManualOneVoiceTwoMusic 

> 

>> % end ManualOne Staff context 

\new Staff = "ManualTwo" « 

\keyTime 
\clef "bass" 

\new Voice { 

\ManualTwoMusic 

> 

>> % end ManualTwo Staff context 

>> 7o end PianoStaff context 
\new Staff = "PedalOrgan" « 

\keyTime 
\clef "bass" 

\new Voice { 

\PedalOrganMusic 

> 

>> 7o end PedalOrgan Staff 

» 

} 7o end Score context 

The above layout of the organ staves is almost perfect; however, there is a slight defect which 
is not visible by looking at just a single system: The distance of the pedal staff to the left hand 
staff should behave approximately the same as the right hand staff to the left hand staff. In 
particular, the stretchability of staves in a PianoStaff context is limited (so that the distance 
between the staves for the left and right hand can’t become too large), and the pedal staff should 
behave similarly. 

Stretchability of staves can be controlled with the staff-staff-spacing property of the 
VerticalAxisGroup ‘graphical object’ (commonly called ‘grob’s within the lilypond documen¬ 
tation) - don’t worry about the details right now; this is fully explained later. For the curious, 
have a look at Section “Overview of modifying properties” in Notation Reference. In this case, 
we want to modify the stretchability sub-property only. Again, for the curious, you can find 
the default values for the staff-staff-spacing property in file ‘scm/def ine-grobs . scm’ by looking 
up the definition of the VerticalAxisGroup grob. The value for stretchability is taken from 
the definition of the PianoStaff context (in file ‘ly/engraver-init. ly’) so that the values are 
identical. 

\score { 

« 7o PianoStaff and Pedal Staff must be simultaneous 
\new PianoStaff << 

\new Staff = "ManualOne" « 
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\keyTime % set key and time signature 
\clef "treble" 

\new Voice { 

\voiceOne 

\ManualOneVoiceOneMusic 

> 

\new Voice { 

\voiceTwo 

\ManualOneVoiceTwoMusic 

> 

>> % end ManualOne Staff context 

\new Staff = "ManualTwo" \with { 

\override VerticalAxisGroup.staff-staff-spacing.stretchability = 5 

> « 

\keyTime 
\clef "bass" 

\new Voice { 

\ManualTwoMusic 

} 

>> % end ManualTwo Staff context 

>> 7o end PianoStaff context 
\new Staff = "PedalOrgan" « 

\keyTime 
\clef "bass" 

\new Voice { 

\PedalOrganMusic 

> 

>> 7o end PedalOrgan Staff 

» 

} 7o end Score context 

That completes the structure. Any three-staff organ music will have a similar structure, 
although the number of voices may vary. All that remains now is to add the music, and combine 
all the parts together. 

\version "2.18.2" 

\header { 

title = "Jesu, meine Freude" 
composer = "J S Bach" 

} 

keyTime = { \key c \minor \time 4/4 } 

ManualOneVoiceOneMusic = \relative g' { 
g4 g f ees I 
d2 c | 

} 

ManualOneVoiceTwoMusic = \relative c 1 { 
eesl6 d ees8~ eesl6 f ees d c8 d” d c" I 
c8 c4 b8 c8. gl6 c b c d | 

> 

ManualTwoMusic = \relative c 1 { 

cl6 b c8~ cl6 b c g a8 g~ gl6 g aes ees | 

fl6 ees f d g aes g f ees d ees8~ eesl6 f ees d | 

> 
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PedalOrganMusic = \relative c { 

r8 cl6 d ees d ees8~ eesl6 a, b g c b c8 I 
rl6 g ees f g f g8 c,2 | 

> 

\score { 

« */. PianoStaff and Pedal Staff must be simultaneous 

\new PianoStaff << 

\new Staff = "ManualQne" « 

\keyTime % set key and time signature 
\clef "treble" 

\new Voice { 

\voiceOne 

\ManualOneVoiceOneMusic 

} 

\new Voice { 

\voiceTwo 

\ManualOneVoiceTwoMusic 

} 

>> % end ManualOne Staff context 

\new Staff = "ManualTwo" \with { 

\override VerticalAxisGroup.staff-staff-spacing.stretchability =5 § 

> « 

\keyTime 
\clef "bass" 

\new Voice { 

\ManualTwoMusic 

> 

>> % end ManualTwo Staff context 

>> 7o end PianoStaff context 
\new Staff = "PedalOrgan" << 

\keyTime 
\clef "bass" 

\new Voice { 

\PedalOrganMusic 

> 

>> 7. end PedalOrgan Staff context 

» 

} 7o end Score context 


Jesu, meine Freude 


J S Bach 
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See also 

Music Glossary: Section “system” in Music Glossary. 

3.4.4 Saving typing with variables and functions 

By this point, you’ve seen this kind of thing: 

hornNotes = \relative c 11 { c4 b dis c } 

\score { 

{ 

\hornNotes 

> 

> 



You may even realize that this could be useful in minimalist music: 
fragmentA = \relative c 11 { a4 a8. bl6 } 
fragment!! = \relative c 11 { a8. gisl6 ees4 } 

violin = \new Staff { 

\fragmentA \fragmentA | 

\fragmentB \fragmentA | 

> 

\score { 

{ 


\violin 
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However, you can also use these variables (also known as macros, or user-defined commands) 
for tweaks: 

dolce = \markup { \italic \bold dolce } 

padText = { \once \override TextScript.padding = #5.0 } 
fthenp =_\markup { 

\dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p 

> 

violin = \relative c 11 { 

\repeat volta 2 { 

c4._\dolce b8 a8 g a b | 

\padText 

c4.~"hi there!" d8 e' f g d | 
c,4.\fthenp b8 c4 c-. I 

> 

> 

\score { 

{ 

\violin 

> 

\layout { ragged-right = ##t } 

> 


hi there! 
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dolce f 2ndp 


These variables are obviously useful for saving typing. But they’re worth considering even if 
you only use them once - they reduce complexity. Let’s look at the previous example without 
any variables. It’s a lot harder to read, especially the last line. 

violin = \relative c 11 { 

\repeat volta 2 { 

c4._\markup { \italic \bold dolce } b8 a8 g a b | 

\once \override TextScript.padding = #5.0 
c4.~"hi there!" d8 e' f g d | 
c,4.\markup { 

\dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p 

} 

b8 c4 c-. | 

> 
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So far we’ve seen static substitution - when LilyPond sees \padText, it replaces it with the 
stuff that we’ve defined it to be (ie the stuff to the right of padtext=). 

LilyPond can handle non-static substitution, too (you can think of these as functions). 
padText = 

#(define-music-function 

(parser location padding) 

(number?) 

#{ 

\once \override TextScript.padding = #padding 

#}) 


\relative c 11 ' { 

c4~"piu mosso" b a b 
\padText #1.8 
c4~"piu mosso" d e f 
\padText #2.6 


c4~"piu mosso" fis a g 


> 


piu mosso 


piu mosso j, * 

^ f- f: f 


piu mosso 






Using variables is also a good way to reduce work if the LilyPond input syntax changes (see 
Section “Updating files with convert-ly” in Application Usage). If you have a single definition 
(such as \dolce) for all your input files (see Section 4.7.3 [Style sheets], page 140), then if 
the syntax changes, you only need to update your single \dolce definition, instead of making 
changes throughout every 1 . ly’ file. 

3.4.5 Scores and parts 

In orchestral music, all notes are printed twice. Once in a part for the musicians, and once in a 
full score for the conductor. Variables can be used to avoid double work. The music is entered 
once, and stored in a variable. The contents of that variable is then used to generate both the 
part and the full score. 

It is convenient to define the notes in a special file. For example, suppose that the file 
‘horn-music. ly’ contains the following part of a horn/bassoon duo 

hornNotes = \relative c { 

\time 2/4 

r4 f8 a | cis4 f | e4 d I 

> 

Then, an individual part is made by putting the following in a file 
\include "horn-music.ly" 

\header { 

instrument = "Horn in F" 

> 
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{ 

\transpose f c' \hornNotes 

> 

The line 

\include "horn-music.ly" 

substitutes the contents of ‘horn-music. ly’ at this position in the file, so hornNotes is defined 
afterwards. The command \transpose f c' indicates that the argument, being \hornNotes, 
should be transposed by a fifth upwards. Sounding f is denoted by notated c ', which corresponds 
with the tuning of a normal French Horn in F. The transposition can be seen in the following 
output 



In ensemble pieces, one of the voices often does not play for many measures. This is denoted 
by a special rest, the multi-measure rest. It is entered with a capital R followed by a duration 
(1 for a whole note, 2 for a half note, etc.). By multiplying the duration, longer rests can be 
constructed. For example, this rest takes 3 measures in 2/4 time 
R2*3 

When printing the part, multi-rests must be condensed. This is done by setting a run-time 
variable 

\set Score.skipBars = ##t 

This command sets the property skipBars in the Score context to true (##t). Prepending the 
rest and this option to the music above, leads to the following result 



The score is made by combining all of the music together. Assuming that the other voice is 
in bassoonNotes in the file ‘bassoon-music. ly’, a score is made with 
\include "bassoon-music.ly" 

\include "horn-music.ly" 

<< 

\new Staff \hornNotes 
\new Staff \bassoonNotes 

» 

leading to 













Chapter 4: Tweaking output 


86 


4 Tweaking output 

This chapter discusses how to modify output. LilyPond is extremely configurable; virtually 
every fragment of output may be changed. 

4.1 Tweaking basics 

4.1.1 Introduction to tweaks 

‘Tweaking’ is a LilyPond term for the various methods available to the user for modifying the 
actions taken during interpretation of the input file and modifying the appearance of the printed 
output. Some tweaks are very easy to use; others are more complex. But taken together the 
methods available for tweaking permit almost any desired appearance of the printed music to 
be achieved. 

In this section we cover the basic concepts required to understand tweaking. Later we give a 
variety of ready-made commands which can simply be copied to obtain the same effect in your 
own scores, and at the same time we show how these commands may be constructed so that you 
may learn how to develop your own tweaks. 

Before starting on this Chapter you may wish to review the section Section 3.3 [Contexts 
and engravers], page 57, as Contexts, Engravers, and the Properties contained within them are 
fundamental to understanding and constructing Tweaks. 

4.1.2 Objects and interfaces 

Tweaking involves modifying the internal operation and structures of the LilyPond program, so 
we must first introduce some terms which are used to describe those internal operations and 
structures. 

The term ‘Object’ is a generic term used to refer to the multitude of internal structures built 
by LilyPond during the processing of an input file. So when a command like \new Staff is 
encountered a new object of type Staff is constructed. That Staff object then holds all the 
properties associated with that particular staff, for example, its name and its key signature, 
together with details of the engravers which have been assigned to operate within that staff’s 
context. Similarly, there are objects to hold the properties of all other contexts, such as Voice 
objects, Score objects, Lyrics objects, as well as objects to represent all notational elements 
such as bar lines, note heads, ties, dynamics, etc. Every object has its own set of property 
values. 

Some types of object are given special names. Objects which represent items of notation on 
the printed output such as note heads, stems, slurs, ties, fingering, clefs, etc are called ‘Layout 
objects’, often known as ‘Graphical Objects’, or ‘Grobs’ for short. These are still objects in 
the generic sense above, and so they too all have properties associated with them, such as their 
position, size, color, etc. 

Some layout objects are still more specialized. Phrasing slurs, crescendo hairpins, ottava 
marks, and many other grobs are not localized in a single place - they have a starting point, an 
ending point, and maybe other properties concerned with their shape. Objects with an extended 
shape like these are called ‘Spanners’. 

It remains to explain what ‘Interfaces’ are. Many objects, even though they are quite dif¬ 
ferent, share common features which need to be processed in the same way. For example, all 
grobs have a color, a size, a position, etc, and all these properties are processed in the same way 
during LilyPond’s interpretation of the input file. To simplify these internal operations these 
common actions and properties are grouped together in an object called a grob-interface. 
There are many other groupings of common properties like this, each one given a name ending 
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in interface. In total there are over 100 such interfaces. We shall see later why this is of 
interest and use to the user. 

These, then, are the main terms relating to objects which we shall use in this chapter. 

4.1.3 Naming conventions of objects and properties 

We met some object naming conventions previously, in Section 3.3 [Contexts and engravers], 
page 57. Here for reference is a list of the most common object and property types together 
with the conventions for naming them and a couple of examples of some real names. We have 
used ‘A’ to stand for any capitalized alphabetic character and ‘aaa’ to stand for any number of 
lower-case alphabetic characters. Other characters are used verbatim. 


Object/property type 

Contexts 
Layout Objects 
Engravers 

Interfaces 

Context Properties 

Layout Object Properties 


Naming convention 

Aaaa or AaaaAaaaAaaa 
Aaaa or AaaaAaaaAaaa 
Aaaa_aaa_engraver 

aaa-aaa-interface 

aaa or aaaAaaaAaaa 

clcLcl Or cLctci - ctclcl- ctclcl 


Examples 

Staff, GrandStaff 
Slur, NoteHead 
CleLengraver, 
Note_heads_engraver 
grob-interface, break- 

aligned-interface 
alignAboveContext, 
skipBars 

direction, beam-thickness 


As we shall see shortly, the properties of different types of object are modified by different 
commands, so it is useful to be able to recognize the types of objects and properties from their 
names. 


4.1.4 Tweaking methods 
The \override command 

We have already met the commands \set and \with, used to change the properties of contexts 
and to remove and add engravers, in Section 3.3.4 [Modifying context properties], page 61, and 
Section 3.3.5 [Adding and removing engravers], page 66. We must now introduce some more 
important commands. 

The command to change the properties of layout objects is \override. Because this com¬ 
mand has to modify internal properties deep within LilyPond its syntax is not as simple as the 
commands you have used so far. It needs to know precisely which property of which object in 
which context has to be modified, and what its new value is to be. Let’s see how this is done. 

The general syntax of this command is: 

\override Context.LayoutObject.layout-property = #value 
This will set the property with the name layout-property of the layout object with the name 
LayoutObject, which is a member of the Context context, to the value value. 

The Context may be omitted (and usually is) when the required context is unambiguously 
implied and is one of lowest level contexts, i.e., Voice, ChordNames or Lyrics, and we shall omit 
it in many of the following examples. We shall see later when it must be specified. 

Later sections deal comprehensively with properties and their values, see Section 4.2.3 [Types 
of properties], page 96. But in this section we shall use just a few simple properties and values 
which are easily understood in order to illustrate the format and use of these commands. 

LilyPond’s primary expressions are musical items like notes, durations, and markups. More 
basic expressions like numbers, strings, and lists are processed in ‘Scheme mode’, which is invoked 
by prefixing the value with ‘#’. Although the values may sometimes have a valid representation 
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in LilyPond’s musical mode, this manual will always use '#’ for their entry for the sake of 
consistency. For more information about Scheme mode, see Section “LilyPond Scheme syntax” 
in Extending. 

\override is the most common command used in tweaking, and most of the rest of this 
chapter will be directed to presenting examples of how it is used. Here is a simple example to 
change the color of the note head: 
c4 d 

\override NoteHead.color = #red 
e4 f | 

\override NoteHead.color = #green 
g4 a b c | 



The \revert command 

Once overridden, the property retains its new value until it is overridden again or a \revert 
command is encountered. The \revert command has the following syntax and causes the value 
of the property to revert to its original default value; note, not its previous value if several 
\override commands have been issued. 

\revert Context.LayoutObject.layout-property 

Again, just like Context in the \override command, Context is often not needed. It will 
be omitted in many of the following examples. Here we revert the color of the note head to the 
default value for the final two notes: 
c4 d 

\override NoteHead.color = #red 
e4 f | 

\override NoteHead.color = #green 
g4 a 

\revert NoteHead.color 
b4 c | 








1 * 1 








— 0 





The \once prefix 

Both the \override and the \set commands may be prefixed by \once. This causes the 
following \override or \set command to be effective only during the current musical moment 
before the property reverts back to its previous value (this can be different from the default if 
another \override is still in effect). Using the same example, we can change the color of a 
single note like this: 
c4 d 

\override NoteHead.color = #red 
e4 f | 

\once \override NoteHead.color = #green 
g4 a 

\revert NoteHead.color 
b c I 
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The \once prefix may also be used in front of many predefined commands to limit their effect 
to one musical moment: 
c4 d 

\once \stemDown 
e4 f I 
g4 a 

\once \hideNotes 
b c I 



However, predefined commands of the form \. . .Neutral, \. . .Off and \un. . . use \revert 
internally rather than \override so prefixing these with \once has no effect. 

The \overrideProperty command 

There is another form of the override command, \overrideProperty, which is occasionally 
required. We mention it here for completeness, but for details see Section “Difficult tweaks” in 
Extending. 

The \tweak command 

The final tweaking command which is available is \tweak. This should be used when several 
objects occur at the same musical moment, but you only want to change the properties of 
selected ones, such as a single note within a chord. Using \override would affect all the notes 
within a chord, whereas \tweak affects just the following item in the input stream. 

Here’s an example. Suppose we wish to change the size of the middle note head (the E) in a 
C major chord. Let’s first see what \once \override would do: 

<c e g>4 

\once \override NoteHead.font-size = #-3 
<c e g>4 
<c e g>4 



We see the override affects all the note heads in the chord. This is because all the notes of a 
chord occur at the same musical moment , and the action of \once is to apply the override to all 
layout objects of the type specified which occur at the same musical moment as the \override 
command itself. 

The \tweak command operates in a different way. It acts on the immediately following item 
in the input stream. In its simplest form, it is effective only on objects which are created directly 
from the following item, essentially note heads and articulations. 

So to return to our example, the size of the middle note of a chord would be changed in this 
way: 

<c e g>4 

<c \tweak font-size #-3 e g>4 
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Note that the syntax of \tweak is different from that of the \override command. The 
context should not be specified; in fact, it would generate an error to do so. Both context and 
layout object are implied by the following item in the input stream. Note also that an equals 
sign should not be present. So the simple form of the \tweak command is 

\tweak layout-property #value 

A \tweak command can also be used to modify just one in a series of articulations, as shown 
here: 

a4~"Black" 

-\tweak color #red “"Red" 

-\tweak color #green _"Green" 

Red 
Black 

Green 

Note that the \tweak command must be preceded by an articulation mark since the tweaked 
expression needs to be applied as an articulation itself. In case of multiple direction overrides 
(~ or _), the leftmost override wins since it is applied last. 

Objects such as stems and accidentals are created later, and not directly from the following 
event. It is still possible to use \tweak on such indirectly created objects by explicitly naming 
the layout object, provided that LilyPond can trace its origin back to the original event: 

<\tweak Accidental.color #red cis4 
\tweak Accidental.color #green es 
g> 




This long form of the \tweak command can be described as 
\tweak layout-object.layout-property value 

The \tweak command must also be used to change the appearance of one of a set of nested 
tuplets which begin at the same musical moment. In the following example, the long triplet 
bracket and the first of the three short brackets begin at the same musical moment, so any 
\override command would apply to both of them. In the example, \tweak is used to distinguish 
between them. The first \tweak command specifies that the long tuplet bracket is to be placed 
above the notes and the second one specifies that the tuplet number is to be printed in red on 
the first short tuplet bracket. 

\tweak direction #up 
\tuplet 3/4 { 

\tweak color #red 
\tuplet 3/2 { c8 [ c c] } 

\tuplet 3/2 { c8 [ c c] } 

\tuplet 3/2 { c8 [ c c] } 

> 
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If nested tuplets do not begin at the same moment, their appearance may be modified in the 
usual way with \override commands: 

\tuplet 3/2 { c8 [ c c] } 

\once \override TupletNumber.text = #tuplet-number::calc-fraction-text 
\tuplet 3/2 { 
c8 [ c] 
c8 [ c] 

\once \override TupletNumber.transparent = ##t 
\tuplet 3/2 { c8 [ c c] } 

\tuplet 3/2 { c8 [ c c] } 

> 



i- 3:2 -1 


See also 

Notation Reference: Section “The tweak command” in Notation Reference. 

4.2 The Internals Reference manual 
4.2.1 Properties of layout objects 

Suppose you have a slur in a score which, to your mind, appears too thin and you’d like to draw 
it a little heavier. How do you go about doing this? You know from the statements earlier about 
the flexibility of LilyPond that such a thing should be possible, and you would probably guess 
that an \override command would be needed. But is there a heaviness property for a slur, 
and if there is, how might it be modified? This is where the Internals Reference manual comes 
in. It contains all the information you might need to construct this and all other \override 
commands. 

Before we look at the Internals Reference a word of warning. This is a reference document, 
which means there is little or no explanation contained within it: its purpose is to present 
information precisely and concisely. This means it might look daunting at first sight. Don’t 
worry! The guidance and explanation presented here will enable you to extract the information 
from the Internals Reference for yourself with just a little practice. 

Let’s use a concrete example with a simple fragment of real music: 

{ 

\key es \major 
\time 6/8 
{ 

r4 bes8 bes[( g]) g | 
g8[( es]) es d[( f]) as | 
as8 g 

> 

\addlyrics { 

The man who | feels love's sweet e — | mo — tion 

> 

> 
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The man who feels love's sweet e - motion 


Suppose now that we decide we would like the slurs to be a little heavier. Is this possible? 
The slur is certainly a layout object, so the question is, ‘Is there a property belonging to a slur 
which controls the heaviness?’ To answer this we must look in the Internals Reference, or IR 
for short. 

The IR for the version of LilyPond you are using may be found on the LilyPond website at 
http://lilypond.org. Go to the documentation page and click on the Internals Reference 
link. For learning purposes you should use the standard HTML version, not the ‘one big page’ 
or the PDF. For the next few paragraphs to make sense you will need to actually do this as you 
read. 

Under the heading Top you will see five links. Select the link to the Backend , which is where 
information about layout objects is to be found. There, under the heading Backend, select the 
link to All layout objects. The page that appears lists all the layout objects used in your version 
of LilyPond, in alphabetic order. Select the link to Slur, and the properties of Slurs are listed. 

An alternative way of finding this page is from the Notation Reference. On one of the pages 
that deals with slurs you may find a link to the Internals Reference. This link will take you 
directly to this page, but if you have an idea about the name of the layout object to be tweaked, 
it is easier to go straight to the IR and search there. 

This Slur page in the IR tells us first that Slur objects are created by the Slur_engraver. 
Then it lists the standard settings. Browse through them looking for a property that might 
control the heaviness of slurs, and you should find 

thickness (number) 

1.2 

Line thickness, generally measured in line-thickness 

This looks a good bet to change the heaviness. It tells us that the value of thickness is a 
simple number, that the default value is 1.2, and that the units are in another property called 
line-thickness. 

As we said earlier, there are few to no explanations in the IR, but we already have enough 
information to try changing the slur thickness. We see that the name of the layout object is 
Slur, that the name of the property to change is thickness and that the new value should be 
a number somewhat larger than 1.2 if we are to make slurs thicker. 

We can now construct the \override command by simply substituting the values we have 
found for the names, omitting the context. Let’s use a very large value for the thickness at first, 
so we can be sure the command is working. We get: 

\override Slur.thickness = #5.0 

Don’t forget the # preceding the new value! 

The final question is, Where should this command be placed?’ While you are unsure and 
learning, the best answer is, ‘Within the music, before the first slur and close to it.’ Let’s do 
that: 

{ 

\key es \major 
\time 6/8 
{ 

7, Increase thickness of all following slurs from 1.2 to 5.0 

\override Slur.thickness = #5.0 

r4 bes8 bes [ ( g]) g | 

g8[( es]) es d[( f]) as I 

as8 g 
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> 

\addlyrics { 

The man who | feels love's sweet e — I mo — tion 

> 

} 



and we see that the slur is indeed heavier. 

So this is the basic way of constructing \override commands. There are a few more com¬ 
plications that we shall meet in later sections, but you now know all the essentials required to 
make up your own - but you will still need some practice. This is provided in the examples 
which follow. 

Finding the context 

But first, what if we had needed to specify the Context? What should it be? We could guess 
that slurs are in the Voice context, as they are clearly closely associated with individual lines of 
music, but can we be sure? To find out, go back to the top of the IR page describing the Slur, 
where it says ‘Slur objects are created by: Slur engraver’. So slurs will be created in whichever 
context the Slur_engraver is in. Follow the link to the Slur_engraver page. At the very 
bottom it tells us that Slur_engraver is part of seven Voice contexts, including the standard 
voice context, Voice, so our guess was correct. And because Voice is one of the lowest level 
contexts which is implied unambiguously by the fact that we are entering notes, we can omit it 
in this location. 

Overriding once only 

As you can see, all the slurs are thicker in the final example above. But what if we wanted just the 
first slur to be thicker? This is achieved with the \once command. Placed immediately before 
the \override command it causes it to change only the slur which begins on the immediately 
following note. If the immediately following note does not begin a slur the command has no 
effect at all - it is not remembered until a slur is encountered, it is simply discarded. So the 
command with \once must be repositioned as follows: 

{ 

\key es \major 
\time 6/8 
{ 

r4 bes8 

7, Increase thickness of immediately following slur only 

\once \override Slur.thickness = #5.0 

bes8[( g]) g I 

g8[( es]) es d[( f]) as | 

as8 g 

> 

\addlyrics { 

The man who | feels love's sweet e — I mo — tion 

> 


> 
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The man who feels love's sweet e - motion 


Now only the first slur is made heavier. 

The \once command can also be used before the \set command. 

Reverting 

Finally, what if we wanted just the first two slurs to be heavier? Well, we could use two 
commands, each preceded by \once placed immediately before each of the notes where the slurs 
begin: 

{ 

\key es \major 
\time 6/8 
{ 

r4 bes8 

7, Increase thickness of immediately following slur only 
\once \override Slur.thickness = #5.0 
bes[( g]) g I 

% Increase thickness of immediately following slur only 
\once \override Slur.thickness = #5.0 
g8[( es]) es d[( f]) as | 
as8 g 

> 

\addlyrics { 

The man who | feels love's sweet e — I mo — tion 

> 

> 



The man who feels love's sweet e - motion 


or we could omit the \once command and use the \revert command to return the thickness 
property to its default value after the second slur: 

{ 

\key es \major 
\time 6/8 
{ 

r4 bes8 

7o Increase thickness of all following slurs from 1.2 to 5.0 
\override Slur.thickness = #5.0 
bes[( g]) g I 
g8[( es]) es 

7o Revert thickness of all following slurs to default of 1.2 
\revert Slur.thickness 
d8[( f]) as | 
as8 g 

> 

\addlyrics { 

The man who | feels love's sweet e — I mo — tion 

> 
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> 



The man who feels love's sweet e - motion 


The \revert command can be used to return any property changed with \override back to 
its default value. You may use whichever method best suits what you want to do. 

That concludes our introduction to the IR, and the basic method of tweaking. Several 
examples follow in the later sections of this Chapter, partly to introduce you to some of the 
additional features of the IR, and partly to give you more practice in extracting information 
from it. These examples will contain progressively fewer words of guidance and explanation. 

4.2.2 Properties found in interfaces 

Suppose now that we wish to print the lyrics in italics. What form of \override command do 
we need to do this? We first look in the IR page listing ‘All layout objects’, as before, and look 
for an object that might control lyrics. We find LyricText, which looks right. Clicking on this 
shows the settable properties for lyric text. These include the font-series and font-size, 
but nothing that might give an italic shape. This is because the shape property is one that is 
common to all font objects, so, rather than including it in every layout object, it is grouped 
together with other similar common properties and placed in an Interface, the font-interface. 

So now we need to learn how to find the properties of interfaces, and to discover what objects 
use these interface properties. 

Look again at the IR page which describes LyricText. At the bottom of the page is a 
list of clickable interfaces which LyricText supports. The list has several items, including 
font-interface. Clicking on this brings up the properties associated with this interface, which 
are also properties of all the objects which support it, including LyricText. 

Now we see all the user-settable properties which control fonts, including 
font-shape (symbol), where symbol can be set to upright, italics or caps. 

You will notice that font-series and font-size are also listed there. This immediately 
raises the question: Why are the common font properties font-series and font-size listed 
under LyricText as well as under the interface font-interface but font-shape is not? The 
answer is that font-series and font-size are changed from their global default values when 
a LyricText object is created, but font-shape is not. The entries in LyricText then tell you 
the values for those two properties which apply to LyricText. Other objects which support 
font-interface will set these properties differently when they are created. 

Let’s see if we can now construct the \override command to change the lyrics to italics. 
The object is LyricText, the property is font-shape and the value is italic. As before, we’ll 
omit the context. 

As an aside, although it is an important one, note that some properties take values that 
are symbols, like italic, and must be preceded by an apostrophe, '. Symbols are then read 
internally by LilyPond. Note the distinction from arbitrary text strings, which would appear as 
"a text string"; for more details about symbols and strings, see Section “Scheme tutorial” in 
Extending. 

So we see that the \override command needed to print the lyrics in italics is: 

\override LyricText.font-shape = #'italic 
This should be placed just in front of the lyrics we wish to affect, like so: 
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\key es \major 
\time 6/8 
{ 

r4 bes8 bes[( g]) g | 
g8[( es]) es d[( f]) as | 
as8 g 

> 

\addlyrics { 

\override LyricText.font-shape = #'italic 

The man who | feels love's sweet e — I mo — tion 

> 

> 



The man who feels love's sweet e - motion 


and the lyrics are all printed in italics. 

/ -N 

Note: In lyrics always leave whitespace between the final syllable and 
the terminating brace. 

v_/ 


See also 

Extending: Section “Scheme tutorial” in Extending. 

4.2.3 Types of properties 

So far we have seen two types of property: number and symbol. To be valid, the value given to 
a property must be of the correct type and obey the rules for that type. The type of property 
is always shown in brackets after the property name in the IR. Here is a list of the types you 
may need, together with the rules for that type, and some examples. You must always add a 
hash symbol, #, of course, to the front of these values when they are entered in the \override 
command, even if the value itself already starts with #. We only give examples for constants 
here: if you want to compute a value using Scheme, see Section “Calculations in Scheme” in 
Extending. 


Property type 

Boolean 

Dimension (in staff 
space) 

Direction 


Integer 

List 


Rules 

Either True or False, represented by #t 
or 

A decimal number (in units of staff 
space) 

A valid direction constant or its numer¬ 
ical equivalent (0 or CENTER indicate a 
neutral direction) 

A whole number 

A sequence of constants or symbols sepa¬ 
rated by spaces, enclosed in parentheses 
and preceded by an apostrophe (quote 
mark) 


Examples 
#t, #f 

2.5, 0.34 

LEFT. CENTER, UP, 1, -1 


3, -1 

' (left-edge staff-bar), 

1 (1), ' (), '(1.0 0.25 0.5) 
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Markup 

Any valid markup 

\markup { \italic "cresc." 
}, "bagpipe" 

Moment 

A fraction of a whole note constructed 
with the make-moment function 

(ly:make-moment 1/4), 

(ly:make-moment 3/8) 

Number 

Any positive or negative, possibly deci¬ 
mal, value 

3, -2.45 

Pair (of numbers) 

Two numbers separated by a ‘space . 
space’ and enclosed in brackets preceded 
by an apostrophe 

'(2 . 3.5), '(0.1 . -3.2) 

Symbol 

Any of the set of permitted sym¬ 
bols for that property, preceded by an 
apostrophe 

'italic, 1 inside 

Unknown 

A procedure, or #f to cause no action 

bend::print, 

ly:text-interface::print, 
#f 

Vector 

See also 

Constants enclosed in #(...). 

#(#t #t #f) 


Extending: Section “Scheme tutorial” in Extending. 

4.3 Appearance of objects 

Let us now put what we have learned into practice with a few examples which show how tweaks 
may be used to change the appearance of the printed music. 

4.3.1 Visibility and color of objects 

In the educational use of music we might wish to print a score with certain elements omitted as 
an exercise for the student, who is required to supply them. As a simple example, let us suppose 
the exercise is to supply the missing bar lines in a piece of music. But the bar lines are normally 
inserted automatically. How do we prevent them printing? 

Before we tackle this, let us remember that object properties are grouped in what are called 
interfaces - see Section 4.2.2 [Properties found in interfaces], page 95. This is simply to group 
together those properties that may be used together to tweak a graphical object - if one of 
them is allowed for an object, so are the others. Some objects then use the properties in some 
interfaces, others use them from other interfaces. The interfaces which contain the properties 
used by a particular grob are listed in the IR at the bottom of the page describing that grob, 
and those properties may be viewed by looking at those interfaces. 

We explained how to find information about grobs in Section 4.2.1 [Properties of layout 
objects], page 91. Using the same approach, we go to the IR to find the layout object which 
prints bar lines. Going via Backend and All layout objects we find there is a layout object called 
BarLine. Its properties include two that control its visibility: break-visibility and stencil. 
Barline also supports a number of interfaces, including the grob-interf ace, where we find the 
transparent and the color properties. All of these can affect the visibility of bar lines (and, 
of course, by extension, many other layout objects too.) Let’s consider each of these in turn. 

The stencil property 

This property controls the appearance of the bar lines by specifying the symbol (glyph) which 
should be printed. In common with many other properties, it can be set to print nothing by 
setting its value to #f. Let’s try it, as before, omitting the implied Context, Voice: 

{ 


\time 12/16 


Chapter 4: Tweaking output 


98 


\override BarLine.stencil = ##f 
c4 b8 c dl6 c d8 | 
g,8 al6 b8 c d4 el6 | 
e8 




ir 

0 


_L 

9— 

-t 


The bar lines are still printed. What is wrong? Go back to the IR and look again at the page 
giving the properties of BarLine. At the top of the page it says “Barline objects are created 
by: Bar.engraver”. Go to the Bar_engraver page. At the bottom it gives a list of Contexts in 
which the bar engraver operates. All of them are of the type Staff, so the reason the \override 
command failed to work as expected is because Barline is not in the default Voice context. 
If the context is specified incorrectly, the command simply does not work. No error message 
is produced, and nothing is logged in the log file. Let’s try correcting it by adding the correct 
context: 

{ 

\time 12/16 

\override Staff.BarLine.stencil = ##f 
c4 b8 c dl6 c d8 | 
g,8 al6 b8 c d4 el6 | 
e8 

> 



Now the bar lines have vanished. Setting the stencil property to #f is such a frequent 
operation that there is a shorthand for it called \omit: 

{ 

\time 12/16 
\omit Staff.BarLine 
c4 b8 c dl6 c d8 I 
g,8 al6 b8 c d4 el6 | 
e8 

> 



Note, though, that setting the stencil property to #f will cause errors when the dimensions 
of the object are required for correct processing. For example, errors will be generated if the 
stencil property of the NoteHead object is set to #f. If this is the case, you can instead use 
the point-stencil function, which sets the stencil to an object with zero size: 

{ 

c4 c 

\once \override NoteHead.stencil = #point-stencil 
c4 c 
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> 



The break-visibility property 

We see from the BarLine properties in the IR that the break-visibility property requires a 
vector of three booleans. These control respectively whether bar lines are printed at the end 
of a line, in the middle of lines, and at the beginning of lines. For our example we want all 
bar lines to be suppressed, so the value we need is #(#f #f #f) (also available under the name 
all-invisible). Let’s try that, remembering to include the Staff context. Note also that 
in writing this value we have ## before the opening parenthesis. One # is required as part of 
vector constant syntax, and the first # is required, as always, to precede the value itself in the 
\override command. 

{ 

\time 12/16 

\override Staff.BarLine.break-visibility = ##(#f #f #f) 
c4 b8 c dl6 c d8 | 
g,8 al6 b8 c d4 el6 | 
e8 

> 



£ 


- Ifff 




And we see this too removes all the bar lines. 

The transparent property 

We see from the properties specified in the grob-interf ace page in the IR that the transparent 
property is a boolean. This should be set to #t to make the grob transparent. In this next 
example let us make the time signature invisible rather than the bar lines. To do this we 
need to find the grob name for the time signature. Back to the ‘All layout objects’ page in 
the IR to find the properties of the TimeSignature layout object. This is produced by the 
Time_signature_engraver which you can check also lives in the Staff context and also sup¬ 
ports the grob-interf ace. So the command to make the time signature transparent is: 

{ 

\time 12/16 

\override Staff.TimeSignature.transparent = ##t 
c4 b8 c dl6 c d8 | 
g,8 al6 b8 c d4 el6 | 
e8 

> 
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Again, setting the transparent property is a rather frequent operation, so we have a shorthand 
for it called \hide: 
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{ 

\time 12/16 

\hide Staff.TimeSignature 
c4 b8 c dl6 c d8 I 
g,8 al6 b8 c d4 el6 | 
e8 

> 



In either case, the time signature is gone, but this command leaves a gap where the time 
signature should be. Maybe this is what is wanted for an exercise for the student to fill it in, 
but in other circumstances a gap might be undesirable. To remove it, the stencil for the time 
signature should be set to #f instead: 

{ 

\time 12/16 

\omit Staff.TimeSignature 
c4 b8 c dl6 c d8 I 
g,8 al6 b8 c d4 el6 | 
e8 

> 


r plTlT 



iF 


\ 


-l 


and the difference is obvious: setting the stencil to #f (possibly via \omit) removes the object 
entirely; making the object transparent (which can be done using \hide) leaves it where it is, 
but makes it invisible. 


The color property 

Finally let us try making the bar lines invisible by coloring them white. (There is a difficulty 
with this in that the white bar line may or may not blank out the staff lines where they cross. 
You may see in some of the examples below that this happens unpredictably. The details of 
why this is so and how to control it are covered in Section “Painting objects white” in Notation 
Reference. But at the moment we are learning about color, so please just accept this limitation 
for now.) 

The grob-interf ace specifies that the color property value is a list, but there is no explana¬ 
tion of what that list should be. The list it requires is actually a list of values in internal units, 
but, to avoid having to know what these are, several ways are provided to specify colors. The 
first way is to use one of the ‘normal’ colors listed in the first table in Section “List of colors” 
in Notation Reference. To set the bar lines to white we write: 

{ 

\time 12/16 

\override Staff.BarLine.color = #white 
c4 b8 c dl6 c d8 | 
g,8 al6 b8 c d4 el6 | 
e8 


> 
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mm 




and again, we see the bar lines are not visible. Note that white is not preceded by an apostrophe 
- it is not a symbol, but a variable. When evaluated, it provides the list of internal values 
required to set the color to white. The other colors in the normal list are variables too. To 
convince yourself this is working you might like to change the color to one of the other variables 
in the list. 

The second way of changing the color is to use the list of XI1 color names in the second list in 
Section “List of colors” in Notation Reference. However, these are mapped to the actual values 
by the function xll-color which converts Xll color symbols into the list of internal values like 
this: 

{ 

\time 12/16 

\override Staff.BarLine.color = #(xll-color 'white) 
c4 b8 c dl6 c d8 | 
g,8 al6 b8 c d4 el6 | 
e8 

> 



Note that in this case the function xll-color takes a symbol as an argument, so the symbol 
must be preceded by an apostrophe to keep it from being evaluated as a variable, and the whole 
function call has to be enclosed in parentheses. 

There is another function, one which converts RGB values into internal colors - the 
rgb-color function. This takes three arguments giving the intensities of the red, green and 
blue colors. These take values in the range 0 to 1. So to set the color to red the value should 
be (rgb-color 10 0) and to white it should be (rgb-color 111): 

{ 

\time 12/16 

\override Staff.BarLine.color = #(rgb-color 111) 
c4 b8 c dl6 c d8 I 
g,8 al6 b8 c d4 el6 | 
e8 

> 



Finally, there is also a grey scale available as part of the Xll set of colors. These range from 
black, 'greyO, to white, 'greylOO, in steps of 1. Let’s illustrate this by setting all the layout 
objects in our example to various shades of grey: 

{ 

\time 12/16 

\override Staff.StaffSymbol.color = #(xll-color 'grey30) 

\override Staff.TimeSignature.color = #(xll-color 'grey60) 

\override Staff.Clef.color = #(xll-color 'grey60) 

\override Voice.NoteHead.color = #(xll-color 'grey85) 
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\override Voice.Stem.color = #(xll-color 'grey85) 
\override Staff.BarLine.color = #(xll-color 'greylO) 
c4 b8 c dl6 c d8 I 
g,8 al6 b8 c d4 el6 | 
e8 



Note the contexts associated with each of the layout objects. It is important to get these right, 
or the commands will not work! Remember, the context is the one in which the appropriate 
engraver is placed. The default context for engravers can be found by starting from the layout 
object, going from there to the engraver which produces it, and on the engraver page in the IR 
it tells you in which context the engraver will normally be found. 

4.3.2 Size of objects 

Let us begin by looking again at the earlier example (see Section 3.1.3 [Nesting music expres¬ 
sions], page 44) which showed how to introduce a new temporary staff, as in an Section “ossia” 
in Music Glossary. 

\new Staff ="main" { 

\relative g' { 
r4 g8 g c4 c8 d | 
e4 r8 
<< 

{ f8 c c } 

\new Staff \with { 

alignAboveContext = #"main" } 

{ f8 f c } 

>> 
r4 | 

> 

> 




Ossia are normally written without clef and time signature, and are usually printed slightly 
smaller than the main staff. We already know now how to remove the clef and time signature - 
we simply set the stencil of each to #f, as follows: 

\new Staff ="main" { 

\relative g' { 
r4 g8 g c4 c8 d | 
e4 r8 
<< 


{ f8 c c } 
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\new Staff \with { 

alignAboveContext = #"main" 

> 

{ 

\omit Staff.Clef 

\omit Staff.TimeSignature 

{ f8 f c } 

> 

>> 
r4 | 

> 

} 


-m-, 

4— 

ff= 

9 


— 

i= 



where the extra pair of braces after the \with clause are required to ensure the enclosed overrides 
and music are applied to the ossia staff. 

But what is the difference between modifying the staff context by using \with and modifying 
the stencils of the clef and the time signature with \override, or in this case \omit? The main 
difference is that changes made in a \with clause are made at the time the context is created, 
and remain in force as the default values for the duration of that context, whereas \set or 
\override commands embedded in the music are dynamic - they make changes synchronized 
with a particular point in the music. If changes are unset or reverted using \unset or \revert 
they return to their default values, which will be the ones set in the \with clause, or if none 
have been set there, the normal default values. 

Some context properties can be modified only in \with clauses. These are those properties 
which cannot sensibly be changed after the context has been created. alignAboveContext and 
its partner, alignBelowContext, are two such properties - once the staff has been created its 
alignment is decided and it would make no sense to try to change it later. 

The default values of layout object properties can also be set in \with clauses. Simply use 
the normal \override command leaving out the context name, since this is unambiguously 
defined as the context which the \with clause is modifying. If fact, an error will be generated 
if a context is specified in this location. 

So we could replace the example above with 

\new Staff ="main" { 

\relative g' { 
r4 g8 g c4 c8 d | 
e4 r8 
<< 

{ f8 c c } 

\new Staff \with { 

alignAboveContext = #"main" 

*/. Don't print clefs in this staff 
\override Clef.stencil = ##f 
l Don't print time signatures in this staff 
\override TimeSignature.stencil = ##f 
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> 

{ f8 f c } 


>> 


r4 | 

> 

} 


4- 


• 

f 

— 

i= 



It turns out that we can also employ the shorthands \hide and \omit for setting the 
transparent property and clearing the stencil here, leading to the result 

\new Staff ="main" { 

\relative g' { 
r4 g8 g c4 c8 d | 
e4 r8 
<< 

{ f8 c c } 

\new Staff \with { 

alignAboveContext = #"main" 

*/. Don't print clefs in this staff 
\omit Clef 

*/. Don't print time signatures in this staff 
\omit TimeSignature 

> 

{ f8 f c } 

>> 
r4 I 

> 

> 


4 — 

K= 

9 



i= 



Finally we come to changing the size of layout objects. 

Some layout objects are created as glyphs selected from a typeface font. These include note 
heads, accidentals, markup, clefs, time signatures, dynamics and lyrics. Their size is changed 
by modifying the font-size property, as we shall shortly see. Other layout objects such as 
slurs and ties - in general, spanner objects - are drawn individually, so there is no font-size 
associated with them. These objects generally derive their size from the objects to which they 
are attached, so usually there is no need to change their size manually. Still other properties 
such as the length of stems and bar lines, thickness of beams and other lines, and the separation 
of staff lines all need to be modified in special ways. 
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Returning to the ossia example, let us first change the font-size. We can do this in two ways. 
We can either change the size of the fonts of each object type, like NoteHeads with commands 
like 

\override NoteHead.font-size = #-2 

or we can change the size of all fonts by setting a special property, fontSize, using \set, or 
by including it in a \with clause (but without the \set). 

\set fontSize = #-2 

Both of these statements would cause the font size to be reduced by 2 steps from its previous 
value, where each step reduces or increases the size by approximately 12%. 

Let’s try it in our ossia example: 

\new Staff ="main" { 

\relative g' { 
r4 g8 g c4 c8 d I 
e4 r8 
<< 

{ f8 c c } 

\new Staff \with { 

alignAboveContext = #"main" 

\omit Clef 

\omit TimeSignature 

*/. Reduce all font sizes by ~24°/„ 

fontSize = #-2 

> 

{ f8 f c } 

>> 
r4 | 

> 

> 


4_ 

) 1 

P 

pz| 





This is still not quite right. The note heads and flags are smaller, but the stems are too long 
in proportion and the staff lines are spaced too widely apart. These need to be scaled down in 
proportion to the font reduction. The next sub-section discusses how this is done. 

4.3.3 Length and thickness of objects 

Distances and lengths in LilyPond are generally measured in staff-spaces, the distance between 
adjacent lines in the staff, (or occasionally half staff spaces) while most thickness properties 
are measured in units of an internal property called line-thickness. For example, by default, 
the lines of hairpins are given a thickness of 1 unit of line-thickness, while the thickness 
of a note stem is 1.3. Note, though, that some thickness properties are different; for example, 
the thickness of beams is controlled by the value of the beam-thickness property, which is 
measured in staff-spaces. 

So how are lengths to be scaled in proportion to the font size? This can be done with the help 
of a special function called magstep provided for exactly this purpose. It takes one argument, 
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the change in font size (#-2 in the example above) and returns a scaling factor suitable for 
reducing other objects in proportion. It is used like this: 

\new Staff ="main" { 

\relative g' { 
r4 g8 g c4 c8 d I 
e4 r8 
<< 

{ f8 c c } 

\new Staff \with { 

alignAboveContext = #"main" 

\omit Clef 

\omit TimeSignature 

fontSize = #-2 

*/. Reduce stem length and line spacing to match 
\override StaffSymbol.staff-space = #(magstep -2) 

> 

{ f8 f c } 

>> 
r4 I 

> 

> 



Since the length of stems and many other length-related properties are always calculated relative 
to the value of the staff-space property these are automatically scaled down in length too. 
Note that this affects only the vertical scale of the ossia - the horizontal scale is determined by 
the layout of the main music in order to remain synchronized with it, so it is not affected by 
any of these changes in size. Of course, if the scale of all the main music were changed in this 
way then the horizontal spacing would be affected. This is discussed later in the layout section. 

This, then, completes the creation of an ossia. The sizes and lengths of all other objects may 
be modified in analogous ways. 

For small changes in scale, as in the example above, the thickness of the various drawn lines 
such as bar lines, beams, hairpins, slurs, etc does not usually require global adjustment. If 
the thickness of any particular layout object needs to be adjusted this can be best achieved by 
overriding its thickness property. An example of changing the thickness of slurs was shown 
above in Section 4.2.1 [Properties of layout objects], page 91. The thickness of all drawn objects 
(i.e., those not produced from a font) may be changed in the same way. 

4.4 Placement of objects 
4.4.1 Automatic behavior 

There are some objects in musical notation that belong to the staff and there are other objects 
that should be placed outside the staff. These are called within-staff objects and outside-staff 
objects respectively. 
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Within-staff objects are those that are located on the staff - note heads, stems, accidentals, 
etc. The positions of these are usually fixed by the music itself — they are vertically positioned 
on specific lines of the staff or are tied to other objects that are so positioned. Collisions of note 
heads, stems and accidentals in closely set chords are normally avoided automatically. There 
are commands and overrides which can modify this automatic behavior, as we shall shortly see. 

Objects belonging outside the staff include things such as rehearsal marks, text and dynamic 
markings. LilyPond’s rule for the vertical placement of outside-staff objects is to place them as 
close to the staff as possible but not so close that they collide with any other object. LilyPond 
uses the outside-staff-priority property to determine the order in which the objects should 
be placed, as follows. 

First, LilyPond places all the within-staff objects. Then it sorts the outside-staff objects 
according to their outside-staff-priority. The outside-staff objects are taken one by one, 
beginning with the object with the lowest outside-staff-priority, and placed so that they 
do not collide with any objects that have already been placed. That is, if two outside-staff 
grobs are competing for the same space, the one with the lower outside-staff-priority will 
be placed closer to the staff. If two objects have the same outside-staff-priority the one 
encountered first will be placed closer to the staff. 

In the following example all the markup texts have the same priority (since it is not explicitly 
set). Note that ‘Text3’ is automatically positioned close to the staff again, nestling under ‘Text2’. 

c2~"Textl" 
c2""Text2" | 
c2~"Text3" 
c2~"Text4" | 


Text2 Text4 
Textl Text3 


Staves are also positioned, by default, as closely together as possible (subject to a minimum 
separation). If notes project a long way towards an adjacent staff they will force the staves 
further apart only if an overlap of the notation would otherwise occur. The following example 
demonstrates this ‘nestling’ of the notes on adjacent staves: 

<< 

\new Staff { 

\relative c' { c4 a, } 

> 

\new Staff { 

\relative c' 1 '' { c4 a, } 

> 
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4.4.2 Within-staff objects 

We have already seen how the commands \voiceXXX affect the direction of slurs, ties, fingering 
and everything else which depends on the direction of the stems - see Section 3.2.2 [Explicitly 
instantiating voices], page 51. These commands are essential when writing polyphonic music to 
permit interweaving melodic lines to be distinguished. But occasionally it may be necessary to 
override this automatic behavior. This can be done for whole sections of music or even for an 
individual note. The property which controls this behavior is the direction property of each 
layout object. We first explain what this does, and then introduce a number of ready-made 
commands which avoid your having to code explicit overrides for the more common modifica¬ 
tions. 

Some layout objects like slurs and ties curve, bend or point either up or down; others like 
stems and flags also move to right or left when they point up or down. This is controlled 
automatically when direction is set. 

The direction property 

The following example shows in bar 1 the default behavior of stems, with those on high notes 
pointing down and those on low notes pointing up, followed by four notes with all stems forced 
down, four notes with all stems forced up, and finally four notes reverted back to the default 
behavior. 

a4 g c a | 

\override Stem.direction = #D0WN 
a4 g c a | 

\override Stem.direction = #UP 
a4 g c a | 

\revert Stem.direction 
a4 g c a | 


-0-1 — h 

1 i i 1 i 1 l-i—1 — i- 

-H 

/Li* J 

|P u 

. p . u m j u » u 



i ~0 _ 0^0 _ 0 ^r 0 


J— 4 

r u 1 = 



Here we use the constants DOWN and UP. These have the values -1 and +1 respectively, and 
these numerical values may be used instead. The value 0 may also be used in some cases. It 
is simply treated as meaning UP for stems, but for some objects it means ‘center’. There is a 
constant, CENTER which has the value 0. 

However, these explicit overrides are not usually used, as there are simpler equivalent pre¬ 
defined commands available. Here is a table of the commonest. The meaning of each is stated 
where it is not obvious. 

Down/Left Up/Right Revert Effect 

\arpeggioArrowDown\arpeggioArrowUp\arpeggioNormal Arrow is at bottom, at top, or 

no arrow 

\dotsDown \dotsUp \dotsNeutral Direction of movement to avoid 

staff lines 

\dynamicDown \dynamicUp \dynamicNeutral 

XphrasingSlurDown XphrasingSlurUp XphrasingSlurNeutralNote: distinct from slur 

commands 

\slurDown \slurUp \slurNeutral 

\stemDown \stemUp \stemNeutral 
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\textSpannerDown \textSpannerUp \textSpannerNeutral Text entered as spanner is be¬ 
low/above staff 

\tieDown \tieUp \tieNeutral 

\tupletDown \tupletUp \tupletNeutral Triplets are below/above notes 

The neutral/normal variants of these commands are implemented using \revert and may 
not be preceded by \once. If you wish to limit the effect of the other commands (which are 
implemented using \override) to a single timestep, you can precede them with \once like you 
would do with explicit overrides. 

Fingering 

The placement of fingering on single notes can also be controlled by the direction property, 
but changing direction has no effect on chords. As we shall see, there are special commands 
which allow the fingering of individual notes of chords to be controlled, with the fingering being 
placed above, below, to the left or to the right of each note. 

First, here’s the effect of direction on the fingering attached to single notes. The first bar 
shows the default behaviour, and the following two bars shows the effect of specifying DOWN and 
UP: 

c4-5 a-3 f-1 c 1 -5 I 

\override Fingering.direction = #D0WN 
c4-5 a-3 f-1 c 1 -5 I 
\override Fingering.direction = #UP 
c4-5 a-3 f-1 c 1 -5 I 



However, overriding the direction property is not the easiest way of manually setting the 
fingering above or below the notes; using _ or ~ instead of - before the fingering number is 
usually preferable. Here is the previous example using this method: 

c4-5 a-3 f-1 c 1 -5 I 
c4_5 a_3 f_l c'_5 | 
c4~5 a~3 f"l c'~5 | 



The direction property is ignored for chords, but the directional prefixes, _ and ~ do work. 
By default, the fingering is automatically placed both above and below the notes of a chord, as 
shown: 

<c-5 g-3>4 
<c-5 g-3 e-2>4 
<c-5 g-3 e-2 c-l>4 


5 5 



1 
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but this may be overridden to manually force all or any of the individual fingering numbers 
above or below: 

<c-5 g-3 e-2 c-l>4 
<c"5 g_3 e_2 c_l>4 
<c"5 g~3 e"2 c_l>4 

5 

5 3 


-4 -* 

5 

2 

- M 

1P1 

! 

h§= 


2 3 1 

1 2 
1 


Even greater control over the placement of fingering of the individual notes in a chord is 
possible by using the \set f ingeringOrientations command. The format of this command 
is: 

\set fingeringOrientations = #'([up] [left/right] [down]) 

\set is used because f ingeringOrientations is a property of the Voice context, created and 
used by the New_f ingering_engraver. 

The property may be set to a list of one to three values. It controls whether fingerings may 
be placed above (if up appears in the list), below (if down appears), to the left (if left appears, 
or to the right (if right appears). Conversely, if a location is not listed, no fingering is placed 
there. LilyPond takes these constraints and works out the best placement for the fingering of 
the notes of the following chords. Note that left and right are mutually exclusive - fingering 
may be placed only on one side or the other, not both. 

f \ 

Note: To control the placement of the fingering of a single note using 
this command it is necessary to write it as a single note chord by placing 
angle brackets round it. 

v_ 4 


Here are a few examples: 

\set fingeringOrientations 
<f-2>4 

<c-l e-2 g-3 b-5>4 

\set fingeringOrientations 

<f-2>4 

<c-l e-2 g-3 b-5>4 | 

\set fingeringOrientations 
<f-2>4 

<c-l e-2 g-3 b-5>4 

\set fingeringOrientations 

<f-2>4 

<c-l e-2 g-3 b-5>4 | 

\set fingeringOrientations 
<f-2>4 

<c-l e-2 g-3 b-5>4 


#'(left) 

#'(left) 


#'(up left down) 

#'(up left) 


#'(right) 


_ 

!_ i 

1 _ 2 

5 

1 _?_ 


1 _; 





1 : 



1 i 


i 



1 : 


/ f * 

5 



5 















3 ! 



3 ! 




3~! 



3^ 




1 


3 

viv 2~m 
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2 
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2 
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2 




2 
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If the fingering seems a little crowded the font-size could be reduced. The default value can 
be seen from the Fingering object in the IR to be -5, so let’s try -7: 


\override Fingering.font-size = #-7 
\set fingeringOrientations = #'(left) 
<f-2>4 


<c-l e-2 g-3 b-5>4 

\set fingeringOrientations 

<f-2>4 

<c-l e-2 g-3 b-5>4 I 

\set fingeringOrientations 

<f-2>4 

<c-l e-2 g-3 b-5>4 

\set fingeringOrientations 

<f-2>4 

<c-l e-2 g-3 b-5>4 | 

\set fingeringOrientations 
<f-2>4 


#'(left) 

#'(up left down) 

#'(up left) 

#'(right) 


<c-l e-2 g-3 b-5>4 


1 

4_l 

i_i 

i_^ 

“1 

i 2 

“1 

i_i 
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1 : 
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1 ! 





i i 






















I 



1 




2 



2 



* 

2 


irm 


8 

2 # 


S 




8 

# 


8 


& 

L2^ 

8 



s 

L l*i 

s 


i 


s 


s 

L i 


i 


4.4.3 Outside-staff objects 

Outside-staff objects are automatically placed to avoid collisions. There are several ways to 
override the automatic placement if the positioning is not optimum. 

The outside-staff-priority property 

Objects with the lower value of the outside-staff-priority property are placed nearer to 
the staff, and other outside-staff objects are then raised as far as necessary to avoid collisions. 
The outside-staff-priority is defined in the grob-interface and so is a property of all 
layout objects. By default it is set to #f for all within-staff objects, and to a numerical value 
appropriate to each outside-staff object when the object is created. The following table shows 
the default numerical values for some of the commonest outside-staff objects. 

Note the unusual names for some of the objects: spanner objects are automatically created 
to control the vertical positioning of grobs which (might) start and end at different musical 
moments, so changing the outside-staff-priority of the underlying grob will have no effect. 
For example, changing outside-staf f-priority of the Hairpin object will have no effect on the 
vertical positioning of hairpins - you must change outside-staff-priority of the associated 
DynamicLineSpanner object instead. This override must be placed at the start of the spanner, 
which might include several linked hairpins and dynamics. 


Layout Object 

Priority 

Controls position of: 

RehearsalMark 

1500 

Rehearsal marks 

MetronomeMark 

1000 

Metronome marks 

VoltaBracketSpanner 

600 

Volta brackets 

TextScript 

450 

Markup text 

MultiMeasureRestText 

450 

Markup text over full-bar 
rests 

OttavaBracket 

400 

Ottava brackets 
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TextSpanner 

350 

Text spanners 

DynamicLineSpanner 

250 

All dynamic markings 

BarNumber 

100 

Bar numbers 

TrillSpanner 

50 

Spanning trills 


Here is an example showing the default placement of some of these. 

% Set details for later Text Spanner 
\override TextSpanner.bound-details.left.text 
= \markup { \small \bold Slower } 
l Place dynamics above staff 
\dynamicUp 

% Start Ottava Bracket 

\ottava #1 

c'4 \startTextSpan 

l Add Dynamic Text and hairpin 

c4\pp\< 

c4 

l Add Text Script 
c4~Text | 
c4 c 

% Add Dynamic Text and terminate hairpin 
c4\ff c \stopTextSpan I 
l Stop Ottava Bracket 
\ottava #0 
c, 4 c c c | 


8va - 

Slower. 


Text 


PP —= ff 


JL / • i i i. 




ff 


J. 5 


This example also shows how to create Text Spanners - text with extender lines above a sec¬ 
tion of music. The spanner extends from the \startTextSpan command to the \stopTextSpan 
command, and the format of the text is defined by the \override TextSpanner command. For 
more details see Section “Text spanners” in Notation Reference. 

It also shows how ottava brackets are created. 

If the default values of outside-staff-priority do not give you the placing you want, the 
priority of any of the objects may be overridden. Suppose we would like the ottava bracket to 
be placed below the text spanner in the example above. All we need to do is to look up the 
priority of OttavaBracket in the IR or in the tables above, and reduce it to a value lower than 
that of a TextSpanner, remembering that OttavaBracket is created in the Staff context: 

°/„ Set details for later Text Spanner 
\override TextSpanner.bound-details.left.text 
= \markup { \small \bold Slower } 

7. Place dynamics above staff 
\dynamicUp 

7o Place following Ottava Bracket below Text Spanners 
\once \override Staff.OttavaBracket.outside-staff-priority = #340 
7„ Start Ottava Bracket 
\ottava #1 
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c'4 \startTextSpan 
7. Add Dynamic Text 
c4\pp 

7o Add Dynamic Line Spanner 
c4\< 

7o Add Text Script 
c4~Text | 
c4 c 

7o Add Dynamic Text 
c4\ff c \stopTextSpan I 
7o Stop Ottava Bracket 
\ottava #0 
c, 4 c c c | 


Slower_ 
8va - 

PP ~ 


Text 


ff 


E 




Note that some of these objects, in particular bar numbers, metronome marks and rehearsal 
marks, live by default in the Score context, so be sure to use the correct context when these 
are being overriden. 

Slurs by default are classed as within-staff objects, but they often appear above the staff if 
the notes to which they are attached are high on the staff. This can push outside-staff objects 
such as articulations too high, as the slur will be placed first. The avoid-slur property of the 
articulation can be set to 1 inside to bring the articulation inside the slur, but the avoid-slur 
property is effective only if the outside-staff-priority is also set to #f. Alternatively, the 
outside-staff-priority of the slur can be set to a numerical value to cause it to be placed 
along with other outside-staff objects according to that value. Here’s an example showing the 
effect of the two methods: 

c4( c"\markup { \tiny \sharp } d4.) c8 | 
c4( 

\once \override TextScript.avoid-slur = #'inside 
\once \override TextScript.outside-staff-priority = ##f 
c4"\markup { \tiny \sharp } d4.) c8 I 
\once \override Slur.outside-staff-priority = #500 
c4( c~\markup { \tiny \sharp } d4.) c8 | 


U 'T' * 


^ 

^ • 

^ * 

<» m m - m m m - m m - m 

f/T\ 1 1 11 1 1 

i i i La 

^ 1 1 J = F =C 

1 1 


1 1 Y 


Changing the outside-staff-priority can also be used to control the vertical placement 
of individual objects, although the results may not always be desirable. Suppose we would 
like “Text3” to be placed above “Text4” in the example under Automatic behavior, above (see 
Section 4.4.1 [Automatic behavior], page 106). All we need to do is to look up the priority of 
TextScript in the IR or in the tables above, and increase the priority of “Text3” to a higher 
value: 
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c2~"Textl" 
c2~"Text2" | 

\once \override TextScript.outside-staff-priority = #500 

c2~"Text3" 

c2~"Text4" | 


Text3 


Text2 


/ p 

a 


rj 








This certainly lifts “Text3” above “Text4” but it also lifts it above “Text2”, and “Text4” 
now drops down. Perhaps this is not so good. What we would really like to do is to position all 
the annotation at the same distance above the staff. To do this, we clearly will need to space the 
notes out horizontally to make more room for the text. This is done using the textLengthOn 
command. 

The \textLengthOn command 

By default, text produced by markup takes up no horizontal space as far as laying out the music 
is concerned. The \textLengthOn command reverses this behavior, causing the notes to be 
spaced out as far as is necessary to accommodate the text: 

\textLengthOn °/ 0 Cause notes to space out to accommodate text 

c2~"Textl" 

c2""Text2" | 

c2~"Text3" 

c2~"Text4" | 


Textl Text2 Text3 Text4 


The command to revert to the default behavior is \textLengthOff. Alternatively, \once 
may be used with \textLengthOn if the effect is to be limited to just a single musical moment. 
The corresponding spacing behavior for rehearsal marks and tempo indications is independently 
controlled with the commands \markLengthOn and \markLengthOf f. 

Markup text will also avoid notes which project above the staff. If this is not desired, the 
automatic displacement upwards may be turned off by setting the priority to #f. Here’s an 
example to show how markup text interacts with such notes. 

% This markup is short enough to fit without collision 
c2""Tex" c 1 ' | 

R1 | 


% This is too long to fit, so it is displaced upwards 
c,, 2~ "Text" c 11 | 

R1 | 


l Turn off collision avoidance 

\once \override TextScript.outside-staff-priority = ##f 
c,,2~"Long Text " c 11 | 
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*/. Turn off collision avoidance 

\once \override TextScript.outside-staff-priority = ##f 
\textLengthOn % and turn on textLengthOn 

c,,2~"Long Text " % Spaces at end are honored 

c' '2 I 


Text 


-S-fst 

2. 



2. 


Lon| 

2. 

pTej 

T 

Long Text : 

2. 

/ — 

B-1 

- 1 

Hi 

_ 

- 1 

Hi 

(2_ 


Hi 

_ 

-1 










Dynamics placement 

Dynamic markings will normally be positioned beneath the staff, but may be positioned above 
with the \dynamicUp command. They will be positioned vertically relative to the note to which 
they are attached, and will float below (or above) all within-staff objects such as phrasing slurs 
and bar numbers. This can give quite acceptable results, as this example shows: 

\clef "bass" 

\key aes \major 
\time 9/8 
\dynamicUp 

bes4.~\f\< \( bes4 bes8 des4\ff\> cl6 bes\! | 
ees,2.~\)\mf ees4 r8 I 



However, if the notes and attached dynamics are close together the automatic placement will 
avoid collisions by displacing later dynamic markings further away, but this may not be the 
optimum placement, as this rather artificial example shows: 

\dynamicUp 

a4\f b\mf a\mp b\p 



Should a similar situation arise in ‘real’ music, it may be preferable to space out the notes a 
little further, so the dynamic markings can all fit at the same vertical distance from the staff. 
We were able to do this for markup text by using the \textLengthOn command, but there is 
no equivalent command for dynamic marks. So we shall have to work out how to do this using 
\override commands. 

Grob sizing 

First we must learn how grobs are sized. All grobs have a reference point defined within them 
which is used to position them relative to their parent object. This point in the grob is then 
positioned at a horizontal distance, X-offset, and at a vertical distance, Y-offset, from its 
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parent. The horizontal extent of the object is given by a pair of numbers, X-extent, which say 
where the left and right edges are relative to the reference point. The vertical extent is similarly 
defined by a pair of numbers, Y-extent. These are properties of all grobs which support the 
grob-interface. 

By default, outside-staff objects are given a width of zero so that they may overlap in 
the horizontal direction. This is done by the trick of making the leftmost extent infinity 
and the rightmost extent minus infinity by setting the extra-spacing-width to ' (+inf .0 . 
-inf .0). To ensure they do not overlap in the horizontal direction we must override this value 
of extra-spacing-width to give them a little extra spacing. The units are the space between 
two staff lines, so moving the left edge half a unit to the left and the right edge half a unit to 
the right should do it: 

\override DynamicText.extra-spacing-width = #'(-0.5 . 0.5) 

Let’s see if this works in our previous example: 

\dynamicUp 

% Extend width by 1 staff space 

\override DynamicText.extra-spacing-width = #'(-0.5 . 0.5) 
a4\f b\mf a\mp b\p 



This looks better, but maybe we would prefer the dynamic marks to be aligned along the 
same baseline rather than going up and down with the notes. The property to do this is 
staff-padding which is covered in the section on collisions (see Section 4.6 [Collisions of ob¬ 
jects], page 120). 


4.5 Vertical spacing 

As a rule, LilyPond’s vertical spacing of musical objects is pretty good. Let’s see how it does 
with a simple song, with 2 voices and piano accompaniment: 
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There’s nothing wrong with the default vertical spacing. However, let’s assume that you’re 
working with a publisher with some specific requirements for vertical spacing of staves and lyrics: 
they want the lyrics spaced away from any notes, they want the piano accompaniment spaced 
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away from the vocal line and they want the two piano staves pushed together tightly. Let’s start 
with the lyrics. 


Lyrics sit within a system, and therefore the commands to space them are found in Section 
“Flexible vertical spacing within systems” in Notation Reference. It tells us that lyrics are 
non-staff lines and therefore the command to change their spacing will refer to the nonstaff 
property. Spacing them away from the staff to which they relate (the top line) will use the 
relatedstaff property. Spacing them from the lower line will use the unrelatedstaf f prop¬ 
erty. The vocal parts are part of a VerticalAxisGroup, so we need to adjust its properties. 
Let’s try it and see if it works. 


« 

\new ChoirStaff 

« 

\new Staff { 

\new Voice = "music" { 
b 1 2 c ' c 1 c ' 

> 

} 

\new Lyrics \with { 

\override VerticalAxisGroup. 

nonstaff-relatedstaff-spacing.padding = #5 
\override VerticalAxisGroup. 

nonstaff-unrelatedstaff-spacing.padding = #5 

> 

\lyricsto "music" { 

Here are some lyrics 

} 

\new Staff { 

\clef bass e'2 f e c 

} 

» 

\new PianoStaff 

« 

\new Staff { 

g''2 c' ' c' ' a'' 

} 

\new Staff { 

\clef bass e2 f c e 

} 

» 

» 
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Here are some lyrics 



i- 1 -■-r 


Well - yes it does, but perhaps too well. When we set the padding to 5, LilyPond adds 5 
staff spaces to the distance between objects, which is too much for us here. We’ll use 2. 

Next, let’s move the piano music away from the vocal parts. The vocal music is a ChoirStaf f, 
so we need to increase the spacing between that group of staves and the piano staff below. We’ll 
do this by changing the basic-distance of the Staff Grouper’s staff group-staff-spacing. 

<< 

\new ChoirStaff \with { 

\override StaffGrouper. 

staffgroup-staff-spacing.basic-distance = #15 

> 

<< 

\new Staff { 

\new Voice = "music" { 
b 1 2 c ' c 1 c 1 

> 

} 

\new Lyrics \with { 

\override VerticalAxisGroup. 

nonstaff-relatedstaff-spacing.padding = #2 
\override VerticalAxisGroup. 

nonstaff-unrelatedstaff-spacing.padding = #2 

} .. 

\lyricsto "music" { 

Here are some lyrics 

} 

\new Staff { 

\clef bass e'2 f e c 

} 

» 

\new PianoStaff 

« 

\new Staff { 

g' '2 c 1 ' c' ' a'' 

} 

\new Staff { 
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\clef bass e2 f c e 

} 

» 



Excellent. Now just for the last requirement to make the piano staves closer together. To 
do this, we again alter the properties of the Staff Grouper, but this time we’re going to reduce 
both the basic-distance and the padding. We can do this as shown below. 

« 

\new ChoirStaff \with { 

\override StaffGrouper. 

staffgroup-staff-spacing.basic-distance = #15 

> 

<< 

\new Staff { 

\new Voice = "music" { 
b 1 2 c ' c 1 c 1 

> 

} 

\new Lyrics \with { 

\override VerticalAxisGroup. 

nonstaff-relatedstaff-spacing.padding = #2 
\override VerticalAxisGroup. 

nonstaff-unrelatedstaff-spacing.padding = #2 

> 

\lyricsto "music" { 

Here are some lyrics 

} 

\new Staff { 

\clef bass e'2 f e c 

} 

» 

\new PianoStaff \with { 

\override StaffGrouper.staff-staff-spacing = #'( 
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(basic-distance . 0) 
(padding . 0)) 

> 

« 

\new Staff { 

g''2 c' ' c' ' a'' 

} 

\new Staff { 

\clef bass e2 f c e 

} 

» 

» 
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That’s put them really close together - but it’s what the publisher wanted. They could be 
moved further apart by altering the padding or basic-distance if wanted. 

There are many ways of altering vertical spacing. A key point to remember is that the 
spacing between objects in a Staf fGroup (like GrandStaf f or PianoStaff groups) is controlled 
by the spacing variables of the StaffGrouper. Spacing from ungrouped staves (like Lyrics 
and Staff) is controlled by the variables of the VerticalAxisGroup. See the Section “Flexible 
vertical spacing paper variables” in Notation Reference and Section “Flexible vertical spacing 
within systems” in Notation Reference for more details. 

4.6 Collisions of objects 
4.6.1 Moving objects 

This may come as a surprise, but LilyPond is not perfect. Some notation elements can overlap. 
This is unfortunate, but in fact rather rare. Usually the need to move objects is for clarity or 
aesthetic reasons - they would look better with a little more or a little less space around them. 

There are three main approaches to resolving overlapping notation. They should be consid¬ 
ered in the following order: 

1. The direction of one of the overlapping objects may be changed using the predefined 
commands listed above for within-staff objects (see Section 4.4.2 [Within-staff objects], 
page 108). Stems, slurs, beams, ties, dynamics, text and tuplets may be repositioned easily 
in this way. The limitation is that you have a choice of only two positions, and neither may 
be suitable. 
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2. The object properties, which LilyPond uses when positioning layout objects, may be mod¬ 
ified using \override. The advantages of making changes to this type of property are (a) 
that some other objects will be moved automatically if necessary to make room and (b) 
the single override can apply to all instances of the same type of object. Such properties 
include: 

• direction 

This has already been covered in some detail - see Section 4.4.2 [Within-staff objects], 
page 108. 

• padding, right-padding, staff-padding 

As an object is being positioned the value of its padding property specifies the gap that 
must be left between itself and the nearest edge of the object against which it is being 
positioned. Note that it is the padding value of the object being placed that is used; 
the padding value of the object which is already placed is ignored. Gaps specified by 
padding can be applied to all objects which support the side-position-interface. 

Instead of padding, the placement of groups of accidentals is controlled by 
right-padding. This property is to be found in the AccidentalPlacement object 
which, note, lives in the Staff context. In the typesetting process the note heads are 
typeset first and then the accidentals, if any, are added to the left of the note heads 
using the right-padding property to determine the separation from the note heads 
and between individual accidentals. So only the right-padding property of the 
AccidentalPlacement object has any effect on the placement of the accidentals. 

The staff-padding property is closely related to the padding property: padding 
controls the minimum amount of space between any object which supports the 
side-position-interface and the nearest other object (generally the note or the 
staff lines); staff-padding applies only to those objects which are always set outside 
the staff - it controls the minimum distance from the staff to the outside-staff object. 
Note that staff-padding has no effect on objects that are positioned relative to the 
note rather than the staff, even though it may be overridden without error for such 
objects - it is simply ignored. 

To discover which padding property is required for the object you wish to reposition, 
you need to return to the IR and look up the object’s properties. Be aware that the 
padding properties might not be located in the obvious object, so look in objects that 
appear to be related. 

All padding values are measured in staff spaces. For most objects, this value is set by 
default to be around 1.0 or less (it varies with each object). It may be overridden if a 
larger (or smaller) gap is required. 

• self-alignment-X 

This property can be used to align the object to the left, to the right, or to center it with 
respect to the parent object’s reference point. It may be used with all objects which 
support the self-alignment-interface. In general these are objects that contain 
text. The values arc LEFT, RIGHT or CENTER. Alternatively, a numerical value between 
-1 and +1 may be specified, where -1 is left-aligned, +1 is right-aligned, and numbers 
in between move the text progressively from left-aligned to right-aligned. Numerical 
values greater than 1 may be specified to move the text even further to the left, or 
less than -1 to move the text even further to the right. A change of 1 in the value 
corresponds to a movement of half the text’s length. 

• extra-spacing-width 

This property is available for all objects which support the item-interface. It takes 
two numbers, the first is added to the leftmost extent and the second is added to the 
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rightmost extent. Negative numbers move the edge to the left, positive to the right, so 
to widen an object the first number must be negative, the second positive. Note that 
not all objects honor both numbers. For example, the Accidental object only takes 
notice of the first (left edge) number. 

• staff-position 

staff-position is a property of the staf f-symbol-ref erencer-interf ace, which is 
supported by objects which are positioned relative to the staff. It specifies the vertical 
position of the object relative to the center line of the staff in half staff-spaces. It is 
useful in resolving collisions between layout objects like multi-measure rests, ties and 
notes in different voices. 

• horizontal-shift 

Within a voice, all the notes occuring at the same musical moment are grouped into a 
note column, and a NoteColumn object is created to control the horizontal positioning 
of that group of notes (see “Note columns” in Section 3.2.2 [Explicitly instantiating 
voices], page 51). If and only if two or more note columns within a single Staff context, 
both with stems in the same direction, occur at the same musical moment, the values 
of their horizontal-shift properties are used to rank them and the columns in the 
higher ranks are progessively offset to avoid collisions of the noteheads. This property 
is set by the \voiceXXX commands and may be overridden directly with an \override 
command or, more usually, by the \shiftOn commands. Note that this property is 
used to rank the note columns for off-setting - it does not specify the magnitude of the 
offset, which is progressively increased in steps based on the note head’s width for each 
rank. The steps are usually of half a note head’s width, but may be a full note head’s 
width when a closely spaced group of notes is involved. 

• force-hshift 

The force-hshift property is a property of a NoteColumn (actually of the 
note-column-interface). Changing it permits a note column to be moved in 
situations where the note columns overlap. Note that it has no effect on note columns 
that do not overlap. It is specified in units appropriate to a note column, viz. the 
note head width of the first voice note. It should be used in complex situations 
where the normal \shiftOn commands (see Section 3.2.2 [Explicitly instantiating 
voices], page 51) do not resolve the note conflict satisfactorily. It is preferable to the 
extra-offset property for this purpose as there is no need to work out the distance 
in staff-spaces, and moving the notes into or out of a NoteColumn affects other actions 
such as merging note heads. 

3. Finally, when all else fails, objects may be manually repositioned relative to the staff center 
line vertically, or by displacing them by any distance to a new position. The disadvantages 
are that the correct values for the repositioning have to be worked out, often by trial and 
error, for every object individually, and, because the movement is done after LilyPond has 
placed all other objects, the user is responsible for avoiding any collisions that might ensue. 
But the main difficulty with this approach is that the repositioning values may need to be 
reworked if the music is later modified. The properties that can be used for this type of 
manual repositioning are: 

extra-offset 

This property applies to any layout object supporting the grob-interf ace. It 
takes a pair of numbers which specify the extra displacement in the horizontal 
and vertical directions. Negative numbers move the object to the left or down. 
The units are staff-spaces. The extra displacement is made after the typeset¬ 
ting of objects is finished, so an object may be repositioned anywhere without 
affecting anything else. 
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positions 

This is most useful for manually adjusting the slope and height of beams, slurs, 
and tuplets. It takes a pair of numbers giving the position of the left and right 
ends of the beam, slur, etc. relative to the center line of the staff. Units are 
staff-spaces. Note, though, that slurs and phrasing slurs cannot be repositioned 
by arbitrarily large amounts. LilyPond first generates a list of possible positions 
for the slur and by default finds the slur that “looks best”. If the positions 
property has been overridden the slur that is closest to the requested positions 
is selected from the list. 

A particular object may not have all of these properties. It is necessary to go to the IR to 
look up which properties are available for the object in question. 

Here is a list of the objects which are most likely to be involved in collisions, together with 
the name of the object which should be looked up in the IR in order to discover which properties 
should be used to move them. 

Object type 

Articulations 
Beams 

Dynamics (vertically) 

Dynamics (horizontally) 

Fingerings 

Rehearsal / Text marks 
Slurs 

Text e.g. "'"text" 

Ties 
Tuplets 

4.6.2 Fixing overlapping notation 

Let’s now see how the properties in the previous section can help to resolve overlapping notation. 

The padding property 

The padding property can be set to increase (or decrease) the distance between symbols that 
are printed above or below notes. 

c2\fermata 

\override Script.padding = #3 
b2\fermata 


Object name 

Script 

Beam 

DynamicLineSpanner 
DynamicText 
Fingering 
RehearsalMark 
Slur 

TextScript 

Tie 

TupletBracket 





l This will not work, see below 
\override MetronomeMark.padding = #3 
\tempo 4 = 120 
cl I 

*/. This works 

\override Score.MetronomeMark.padding = #3 
\tempo 4 = 80 
dl I 
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J. 


J. 


80 


120 


E 


TT 


Note in the second example how important it is to figure out what context handles a certain 
object. Since the MetronomeMark object is handled in the Score context, property changes in 
the Voice context will not be noticed. For more details, see Section “Modifying properties” in 
Notation Reference. 

If the padding property of an object is increased when that object is in a stack of objects 
being positioned according to their outside-staff-priority, then that object and all objects 
outside it are moved. 


The right-padding property 

The right-padding property affects the spacing between the accidental and the note to which 
it applies. It is not often required, but the default spacing may be wrong for certain special 
accidental glyphs or combination of glyphs used in some microtonal music. These have to be 
entered by overriding the accidental stencil with a markup containing the desired symbol(s), like 
this: 


sesquisharp = \markup { \sesquisharp } 
\relative c 11 { 
c4 

% This prints a 
\once \override 
\once \override 
cis4 c 

% This improves 
\once \override 
\once \override 
\once \override 
cis4 I 

> 


sesquisharp but the spacing is too small 
Accidental.stencil = #ly:text-interface::print 
Accidental.text = #sesquisharp 

the spacing 

Score.AccidentalPlacement.right-padding = #0.6 
Accidental.stencil = #ly:text-interface::print 
Accidental.text = #sesquisharp 


C ppjjpg 


This necessarily uses an override for the accidental stencil which will not be covered until later. 
The stencil type must be a procedure, here changed to print the contents of the text property 
of Accidental, which itself is set to be a sesquisharp sign. This sign is then moved further away 
from the note head by overriding right-padding. 

The staff-padding property 

staf f-padding can be used to align objects such as dynamics along a baseline at a fixed distance 
from the staff, when no other notation forces them further from the staff. It is not a property 
of DynamicText but of DynamicLineSpanner. This is because the baseline should apply equally 
to all dynamics, including those created as extended spanners. So this is the way to align the 
dynamic marks in the example taken from the previous section: 

\override DynamicLineSpanner.staff-padding = #3 
a4\f b\mf a\p b\mp 
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fmfpmp 


The self-alignment-X property 

The following example shows how to adjust the position of a string fingering object relative to 
a note’s stem by aligning the right edge with the reference point of the parent note: 

\voiceOne 

<a\2> 

\once \override StringNumber.self-alignment-X = #RIGHT 
<a\2> 



The staff-position property 

Multimeasure rests in one voice can collide with notes in another. Since these rests are typeset 
centered between the bar lines, it would require significant effort for LilyPond to figure out 
which other notes might collide with it, since all the current collision handling between notes 
and between notes and rests is done only for notes and rests that occur at the same time. Here’s 
an example of a collision of this type: 

« { c4 c c c } \\ { R1 } » 


The best solution here is to move the multimeasure rest down, since the rest is in voice two. 
The default in \voiceTwo (i.e. in the second voice of a «{. . .} \\ {. . .}» construct) is that 
staff-position is set to -4 for MultiMeasureRest, so we need to move it, say, four half-staff 
spaces down to -8. 

<< 

{ c4 c c c } 

\\ 

\override MultiMeasureRest.staff-position = #-8 
{ R1 > 




This is better than using, for example, extra-offset, because the ledger line above the rest 
is inserted automatically. 

The extra-offset property 

The extra-offset property provides complete control over the positioning of an object both 
horizontally and vertically. 

In the following example, the second fingering is moved a little to the left, and 1.8 staff space 
downwards: 
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\stemUp 
f 4-5 

\once \override Fingering.extra-offset = #'(-0.3 . -1.8) 
f 4-5 



The positions property 

The positions property allows the vertical position and hence the slope of triplets, slurs, phras¬ 
ing slurs and beams to be controlled manually. 

Here’s an example in which the phrasing slur and slur collide: 
a8 \( ( a 1 16 ) a \) 



One possibility would be to move the two ends of the phrasing slur higher. We can try setting 
the left end to 2.5 staff-spaces above the centre line and the right end to 4.5 above, and LilyPond 
will select the phrasing slur from the candidates it has found with its end points closest to these: 

\once \override PhrasingSlur.positions = #'(2.5 . 4.5) 
a8 \( ( a'16 ) a \) 



This is an improvement, but why not lower the right end of the slur a little? If you try it 
you’ll find it can’t be done in this way. That’s because there are no candidate slurs lower than 
the one already selected, and in this case the positions property has no effect. However, ties, 
slurs and phrasing slurs can be positioned and shaped very precisely when necessary. To learn 
how to do this, see Section “Modifying ties and slurs” in Notation Reference. 

Here’s a further example. We see that the beams collide with the ties: 


\time 4/2 

« 

{ c'l ~ c'2. e 1 8 f 1 } 

\\ 

{ e''8 e 1 ' e 11 e 1 ' e'' e'' e' 1 e' 1 

» 

« 

{ c'l ~ c '2. e'8 f 1 } 

\\ 

{ e''8 e 1 ' e 11 e 1 ' e' 1 e'' e' 1 e' 1 

» 


f"2g" > 


f "2 g" > 

























Chapter 4: Tweaking output 


127 



This can be resolved by manually moving both ends of the beam up from their position at 1.81 
staff-spaces below the center line to, say, 1: 


\time 4/2 

« 

{ c 1 1 ~ c ' 2. e 1 8 f' } 

\\ 

{ 

\override Beam.positions = #'(-1 
e' 1 8 e 1 ' e 1 ' e 1 ' e' 1 e' 1 e' 1 e 11 

} 

» 

« 

{ c 1 1 ~ c ' 2. e 1 8 f' } 

\\ 

{ e''8 e 1 ' e 11 e 1 ' e ,, e' , e' , e ,, 


- 1 ) 

f''2 g 11 


f’'2 g 11 


> 



Note that the override continues to apply in the first voice of the second measure of eighth notes, 
but not to any of the beams in the second voice. 

The force-hshift property 

We can now see how to apply the final corrections to the Chopin example introduced at the end 
of Section 3.2.1 [I’m hearing Voices], page 47, which was left looking like this: 

\new Staff \relative c 11 { 

\key aes \major 

« 

{ c2 aes4. bes8 } 

\\ 

{ <ees, c>2 des } 

w 

w 

{ aes '2 f4 fes } 

» I 

<c ees aes c>l | 



The inner note of the first chord (i.e. the A-flat in the fourth Voice) need not be shifted away 
from the note column of the higher note. We might expect to correct this by using \shiftOff, 
but this will cause warnings about clashing note columns. Instead, we set force-hshift, which 
is a property of NoteColumn, of this note to zero. 
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In the second chord we prefer the F to line up with the A-flat and the lowest note to be 
positioned slightly right to avoid a collision of stems. We achieve this by setting force-hshift 
in the NoteColumn of the low D-flat to move it to the right by half a staff-space, and setting 
force-hshift for the F to zero. Note that we use \once to avoid the settings propagating 
beyond the immediate musical moment, although in this small example the \once and the 
second \override in Voice four could be omitted. This would not be good practice. 

Here’s the final result: 

\new Staff \relative c 11 { 

\key aes \major 

« 

{ c2 aes4. bes8 } 

\\ 

{ <ees, c>2 \once \override NoteColumn.force-hshift =0.5 des } 

\\ 

\\ 

{ \once \override NoteColumn.force-hshift = 0 aes'2 
\once \override NoteColumn.force-hshift = 0 f4 fes } 

» I 

<c ees aes c>l | 

> 


X L^i t> /. 7 

j 1 N 


3£E?= 2=33=1 


-H- 


* f T 

^— 


4.6.3 Real music example 

We end this section on Tweaks by showing the steps to be taken to deal with a tricky example 
which needs several tweaks to produce the desired output. The example has been deliberately 
chosen to illustrate the use of the Notation Reference to resolve unusual problems with notation. 
It is not representative of the more usual engraving process, so please do not let these difficulties 
put you off! Fortunately, difficulties like these are not very common! 

The example is from Chopin’s Premiere Ballade, Op. 23, bars 6 to 9, the transition from the 
opening Lento to Moderato. Here, first, is what we want the output to look like, but to avoid 
over-complicating the example too much we have left out the dynamics, fingering and pedalling. 



We note first that the right hand part in the third bar requires four voices. These are the 
five beamed eighth notes, the tied C, the half-note D which is merged with the eighth note D, 
and the dotted quarter note F-sharp, which is also merged with the eighth note at the same 
pitch. Everything else is in a single voice, so the easiest way is to introduce these extra three 
voices temporarily at the time they are needed. If you have forgotten how to do this, look at 
Section 3.2.1 [I’m hearing Voices], page 47 and Section 3.2.2 [Explicitly instantiating voices], 
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page 51. Here we choose to use explicitly instantiated voices for the polyphonic passage, as 
LilyPond is better able to avoid collisions if all voices are instantiated explicitly in this way. 

So let us begin by entering the notes as two variables, setting up the staff structure in a score 
block, and seeing what LilyPond produces by default: 

rhMusic = \relative c' 1 { 

\new Voice { 
r2 c4. g8 I 
besl~ | 

\time 6/4 
bes2. r8 

l Start polyphonic section of four voices 
<< 

{ c,8 d fis bes a } % continuation of main voice 

\new Voice { 

\voiceTwo 
c,8~ c2 

> 

\new Voice { 

\voiceThree 
s8 d2 

> 

\new Voice { 

\voiceFour 
s4 fis4. 

> 

» I 

g2. % continuation of main voice 

> 

> 

lhMusic = \relative c 1 { 
r2 <c g ees>2 | 

<d g, d>l I 
r2. d,,4 r4 r | 
r4 

> 

\score { 

\new PianoStaff « 

\new Staff = "RH" « 

\key g \minor 
\rhMusic 

>> 

\new Staff = "LH" « 

\key g \minor 
\clef "bass" 

\lhMusic 

>> 

» 


> 
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All the notes are right, but the appearance is far from satisfactory. The tie collides with the 
change in time signature, some notes are not merged together, and several notation elements 
are missing. Let’s first deal with the easier things. We can easily add the left hand slur and the 
right hand phrasing slur, since these were all covered in the Tutorial. Doing this gives: 
rhMusic = \relative c' 1 { 

\new Voice { 
r2 c4.\( g8 | 
besl~ | 

\time 6/4 
bes2. r8 

% Start polyphonic section of four voices 
<< 

{ c,8 d fis bes a } % continuation of main voice 

\new Voice { 

\voiceTwo 
c,8~ c2 

> 

\new Voice { 

\voiceThree 
s8 d2 

> 

\new Voice { 

\voiceFour 
s4 fis4. 

> 

» I 

g2.\) 7, continuation of main voice 

> 

> 

lhMusic = \relative c' { 
r2 <c g ees>2( | 

<d g, d>l) | 
r2. d,,4 r4 r | 
r4 


\score { 

\new PianoStaff « 

\new Staff = "RH" « 
\key g \minor 
\rhMusic 

>> 

\new Staff = "LH" « 
\key g \minor 
\clef "bass" 

\lhMusic 
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>> 

» 

> 



The first bar is now correct. The second bar contains an arpeggio and is terminated by a 
double bar line. How do we do these, as they have not been mentioned in this Learning Manual? 
This is where we need to turn to the Notation Reference. Looking up ‘arpeggio’ and ‘bar line’ 
in the index quickly shows us that an arpeggio is produced by appending \arpeggio to a chord, 
and a double bar line is produced by the \bar "II" command. That’s easily done. We next 
need to correct the collision of the tie with the time signature. This is best done by moving the 
tie upwards. Moving objects was covered earlier in Section 4.6.1 [Moving objects], page 120, 
which says that objects positioned relative to the staff can be moved vertically by overriding 
their staff-position property, which is specified in half staff spaces relative to the center line 
of the staff. So the following override placed just before the first tied note would move the tie 
up to 3.5 half staff spaces above the center line: 

\once \override Tie . staf f-position = #3.5 

This completes bar two, giving: 

rhMusic = \relative c' 1 { 

\new Voice { 
r2 c4.\( g8 | 

\once \override Tie.staff-position = #3.5 
besl~ | 

\bar "II" 

\time 6/4 
bes2. r8 

7, Start polyphonic section of four voices 
<< 

{ c,8 d fis bes a } % continuation of main voice 

\new Voice { 

\voiceTwo 
c,8~ c2 

> 

\new Voice { 

\voiceThree 
s8 d2 

> 

\new Voice { 

\voiceFour 
s4 fis4. 

> 

» I 

g2.\) 7, continuation of main voice 

> 
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> 

lhMusic = \relative c' { 
r2 <c g ees>2( | 

<d g, d>l)\arpeggio | 
r2. d,,4 r4 r | 
r4 

> 

\score { 

\new PianoStaff « 

\new Staff = "RH" « 
\key g \minor 
\rhMusic 

>> 

\new Staff = "LH" « 
\key g \minor 
\clef "bass" 

\lhMusic 

>> 

» 

> 



On to bar three and the start of the Moderato section. The tutorial showed how to add 
bold text with the \markup command, so adding “Moderato” in bold is easy. But how do we 
merge notes in different voices together? This is where we need to turn again to the Notation 
Reference for help. A search for “merge” in the Notation Reference index quickly leads us to 
the commands for merging differently headed and differently dotted notes in Section “Collision 
resolution” in Notation Reference. In our example we need to merge both types of note for the 
duration of the polyphonic section in bar 3, so using the information we find in the Notation 
Reference we add 

\mergeDifferentlyHeadedOn 
\mergeDifferentlyDottedOn 

to the start of that section and 

\mergeDifferentlyHeadedOff 
\mergeDifferentlyDottedOff 


to the end, giving: 
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These overrides have merged the two F-sharp notes, but not the two on D. Why not? The 
answer is there in the same section in the Notation Reference - notes being merged must have 
stems in opposite directions and two notes cannot be merged successfully if there is a third note 
in the same note column. Here the two D’s both have upward stems and there is a third note - 
the C. We know how to change the stem direction using \stemDown, and the Notation Reference 
also says how to move the C - apply a shift using one of the \shift commands. But which 
one? The C is in voice two which has shift off, and the two D’s are in voices one and three, 
which have shift off and shift on, respectively. So we have to shift the C a further level still 
using \shiftOnn to avoid it interfering with the two D’s. Applying these changes gives: 
rhMusic = \relative c 1 ' { 

\new Voice { 
r2 c4.\( g8 | 

\once \override Tie.staff-position = #3.5 
besl~ | 

\bar "II" 

\time 6/4 

bes2.~\markup { \bold "Moderato" } r8 
\mergeDifferentlyHeadedOn 
\mergeDifferentlyDottedOn 
°/ 0 Start polyphonic section of four voices 
<< 

{ c,8 d fis bes a } % continuation of main voice 

\new Voice { 

\voiceTwo 

*/. Move the c2 out of the main note column 
l so the merge will work 
c,8~ \shiftOnn c2 

> 

\new Voice { 

\voiceThree 

*/. Stem on the d2 must be down to permit merging 
s8 \stemDown d2 

> 

\new Voice { 

\voiceFour 
s4 fis4. 

> 

» I 

\mergeDifferentlyHeadedOff 
\mergeDifferentlyDottedOff 
g2.\) 7, continuation of main voice 

> 

> 

lhMusic = \relative c' { 
r2 <c g ees>2( | 
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<d g, d>l)\arpeggio | 
r2. d,,4 r4 r | 
r4 

> 

\score { 

\new PianoStaff « 

\new Staff = "RH" « 
\key g \minor 
\rhMusic 

>> 

\new Staff = "LH" « 
\key g \minor 
\clef "bass" 
\lhMusic 

>> 

» 

> 



Nearly there. Only two problems remain: The downward stem on the merged D should not 
be there, and the C would be better positioned to the right of the D’s. We know how to do 
both of these from the earlier tweaks: we make the stem transparent, and move the C with the 
force-hshift property. Here’s the final result: 

rhMusic = \relative c' 1 { 

\new Voice { 
r2 c4.\( g8 | 

\once \override Tie.staff-position = #3.5 
besl~ | 

\bar "M" 

\time 6/4 

bes2.~\markup { \bold "Moderato" } r8 
\mergeDifferentlyHeadedOn 
\mergeDifferentlyDottedOn 
7, Start polyphonic section of four voices 
<< 

{ c,8 d fis bes a } °/ 0 continuation of main voice 

\new Voice { 

\voiceTwo 
c, 8~ 

7o Reposition the c2 to the right of the merged note 
\once \override NoteColumn.force-hshift = #1.0 
Y, Move the c2 out of the main note column 
7o so the merge will work 
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\shiftOnn 

c2 

> 

\new Voice { 

\voiceThree 

s8 

*/. Stem on the d2 must be down to permit merging 
\stemDown 

°/ 0 Stem on the d2 should be invisible 
\tweak Stem.transparent ##t 
d2 

> 

\new Voice { 

\voiceFour 
s4 fis4. 

> 

» I 

\mergeDifferentlyHeadedOff 
\mergeDifferentlyDottedOff 
g2.\) % continuation of main voice 

> 

> 

lhMusic = \relative c 1 { 
r2 <c g ees>2( | 

<d g, d>l)\arpeggio | 
r2. d,,4 r4 r | 
r4 

} 

\score { 

\new PianoStaff « 

\new Staff = "RH" « 

\key g \minor 
\rhMusic 

>> 

\new Staff = "LH" « 

\key g \minor 
\clef "bass" 

\lhMusic 

>> 

» 

> 


Moderato 
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4.7 Further tweaking 
4.7.1 Other uses for tweaks 
Tying notes across voices 

The following example demonstrates how to connect notes in different voices using ties. Nor¬ 
mally, only two notes in the same voice can be connected with ties. By using two voices, with 
the tied notes in one of them 



and blanking the first up-stem in that voice, the tie appears to cross voices: 
<< 

{ 

\tweak Stem.transparent ##t 
b8~ b\noBeam 

> 

w 

{ b8[ g] } 

>> 



To make sure that the just-blanked stem doesn’t squeeze the tie too much, we can lengthen 
the stem by setting the length to 8, 

<< 

{ 

\tweak Stem.transparent ##t 
\tweak Stem.length #8 
b8~ b\noBeam 

> 

w 

{ b8[ g] } 

» 



Now for overriding the transparency of a graphical object, we could have used the shorthand 
\hide as explained above. Tweaking is a different operation, affecting only properties generated 
from a single music expression. It turns out that we can convert overrides into tweaks using 
\single, making it possible to rewrite the above example as 
<< 

{ 

\single \hide Stem 
\single \hide Flag 
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\tweak 

Stem.length #8 

b8~ b\noBeam 

> 


\\ 


{ b8[ g] 

} 

>> 




In this particular case, the difference to \once \hide is not apparent. It is important when 
there are several objects at the same point in musical time (like noteheads in a chord). In that 
case, \once will affect all of those objects while \single will only affect a single one, the one 
generated by the immediately following music expression. 

Simulating a fermata in MIDI 

For outside-staff objects it is usually better to override the object’s stencil property rather 
than its transparent property when you wish to remove it from the printed output. Setting the 
stencil property of an object to #f will remove that object entirely from the printed output. 
This means it has no effect on the placement of other objects placed relative to it. 

For example, if we wished to change the metronome setting in order to simulate a fermata in 
the MIDI output we would not want the metronome markings to appear in the printed output, 
and we would not want it to influence the spacing between the two systems or the positions of 
adjacent annotations on the staff. So setting its stencil property to #f would be the best way. 
We show here the effect of the two methods: 

\score { 

\relative c' 1 { 

% Visible tempo marking 
\tempo 4=120 
a4 a a 

\once \hide Score.MetronomeMark 

% Invisible tempo marking to lengthen fermata in MIDI 
\tempo 4=80 
a4\fermata | 

°/ 0 New tempo for next section 
\tempo 4=100 
a4 a a a I 

> 

\layout { } 

\midi { } 

> 


J. 


J- 


100 


120 






35 


\score { 

\relative c' 1 { 
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l Visible tempo marking 
\tempo 4=120 
a4 a a 

\once \omit Score.MetronomeMark 

7, Invisible tempo marking to lengthen fermata in MIDI 
\tempo 4=80 
a4\fermata | 

7o New tempo for next section 
\tempo 4=100 
a4 a a a | 

> 

\layout { } 

\midi { } 


J. 


120 d= 100 

JJJJ I JJJJ 


TN J = 


00 


U 


Both methods remove the metronome mark which lengthens the fermata from the printed output, 
and both affect the MIDI timing as required, but the transparent metronome mark in the first 
line forces the following tempo indication too high while the second (with the stencil removed) 
does not. 

See also 

Music Glossary: Section “system” in Music Glossary. 

4.7.2 Using variables for layout adjustments 

Override commands are often long and tedious to type, and they have to be absolutely correct. 
If the same overrides are to be used many times it may be worth defining variables to hold them. 

Suppose we wish to emphasize certain words in lyrics by printing them in bold italics. The 
\italic and \bold commands only work within lyrics if they are embedded, together with the 
word or words to be modified, within a \markup block, which makes them tedious to enter. The 
need to embed the words themselves prevents their use in simple variables. As an alternative 
can we use \override and \revert commands? 

\override Lyrics.LyricText.font-shape = #'italic 
\override Lyrics.LyricText.font-series = #'bold 

\revert Lyrics.LyricText.font-shape 
\revert Lyrics.LyricText.font-series 

These would also be extremely tedious to enter if there were many words requiring emphasis. 
But we can define these as two variables and use those to bracket the words to be emphasized. 
Another advantage of using variables for these overrides is that the spaces around the dot are 
not necessary, since they are not being interpreted in Uyricmode directly. Here’s an example of 
this, although in practice we would choose shorter names for the variables to make them quicker 
to type: 

emphasize = { 

\override Lyrics.LyricText.font-shape = #'italic 
\override Lyrics.LyricText.font-series = #'bold 

> 
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normal = { 

\revert Lyrics.LyricText.font-shape 
\revert Lyrics.LyricText.font-series 

> 

global = { \key c \major \time 4/4 \partial 4 } 

SopranoMusic = \relative c 1 { c4 | e4. e8 g4 g I a4 a g } 

AltoMusic = \relative c 1 { c4 | c4. c8 e4 e I f4 f e } 

TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 } 

BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 } 

VerseOne = \lyrics { 

E — I ter — nal \emphasize Fa — ther, | \normal strong to save, 

} 

VerseTwo = \lyricmode { 

0 | \once \emphasize Christ, whose voice the | wa — ters heard, 

} 

VerseThree = \lyricmode { 

0 | \emphasize Ho — ly Spi — rit, | \normal who didst brood 

} 

VerseFour = \lyricmode { 

0 | \emphasize Tri — ni — ty \normal of | love and pow'r 

> 

\score { 

\new ChoirStaff « 

\new Staff << 

\clef "treble" 

\new Voice = "Soprano" { \voiceOne \global \SopranoMusic } 
\new Voice = "Alto" { \voiceTwo \AltoMusic } 

\new Lyrics \lyricsto "Soprano" { WerseOne } 

\new Lyrics \lyricsto "Soprano" { WerseTwo } 

\new Lyrics \lyricsto "Soprano" { WerseThree } 

\new Lyrics \lyricsto "Soprano" { WerseFour } 

>> 

\new Staff << 

\clef "bass" 

\new Voice = "Tenor" { \voiceOne \TenorMusic } 

\new Voice = "Bass" { \voiceTwo \BassMusic } 

>> 

» 


> 
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'V P f f f 


E - ter - nal Fa - ther, strong to save, 
O Christ, whose voice the wa - ters heard, 
O Ho - ly Spi rit, who didst brood 
O Tri - ni - ty of love and pow’r 


wm 




J- 


MUM 


r p r r 


4.7.3 Style sheets 

The output that LilyPond produces can be heavily modified; see Chapter 4 [Tweaking output], 
page 86, for details. But what if you have many input files that you want to apply your tweaks 
to? Or what if you simply want to separate your tweaks from the actual music? This is quite 
easy to do. 

Let’s look at an example. Don’t worry if you don’t understand the parts with all the #(). 
This is explained in Section 4.7.5 [Advanced tweaks with Scheme], page 145. 
mpdolce = 

\tweak self-alignment-X #-0.6 
#(make-dynamic-script 

#{ \markup { \dynamic mp \normal-text \italic \bold dolce } #}) 


inst = 

#(define-music-function 

(parser location string) 

(string?) 

#{ <>~\markup \bold \box #string #}) 

\relative c 11 { 

\tempo 4=50 

a4.\mpdolce d8 cis4—\glissando a I 

b4 bes a2 I 

\inst "Clarinet" 

cis4.\< d8 e4 fis I 

g8(\! fis)-. e( d)-. cis2 | 

> 


J. 


50 





n 




mp dolce 


Let’s do something about the mpdolce and inst definitions. They produce the output we 
desire, but we might want to use them in another piece. We could simply copy-and-paste them 
at the top of every file, but that’s an annoyance. It also leaves those definitions in our input 
files, and I personally find all the #() somewhat ugly. Let’s hide them in another file: 

111 save this to a file called "definitions.ily" 
mpdolce = 

\tweak self-alignment-X #-0.6 
#(make-dynamic-script 
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#{ \markup { \dynamic mp \normal-text \italic \bold dolce } #}) 


inst = 

#(define-music-function 

(parser location string) 

(string?) 

#{ <>~\markup \bold \box #string #}) 

We will refer to this file using the \include command near the top of the music file. (The 
extension ily’ is used to distinguish this included file, which is not meant to be compiled on 
its own, from the main hie.) Now let’s modify our music (let’s save this hie as ‘music.ly’). 
\include "definitions.ily" 

\relative c 11 { 

\tempo 4=50 

a4.\mpdolce d8 cis4—\glissando a I 
b4 bes a2 | 

\inst "Clarinet" 

cis4.\< d8 e4 fis I 

g8(\! fis)-. e( d)-. cis2 | 

> 



That looks better, but let’s make a few changes. The glissando is hard to see, so let’s make it 
thicker and closer to the note heads. Let’s put the metronome marking above the clef, instead 
of over the hrst note. And finally, my composition professor hates ‘C’ time signatures, so we’d 
better make that ‘4/4’ instead. 

Don’t change ‘music, ly’, though. Replace our ‘definitions. ily’ with this: 

TO definitions.ily 
mpdolce = 

\tweak self-alignment-X #-0.6 
#(make-dynamic-script 

#{ \markup { \dynamic mp \normal-text \italic \bold dolce } #}) 


inst = 

#(define-music-function 

(parser location string) 

(string?) 

#{ <>~\markup \bold \box #string #}) 

\layout{ 

\context { 

\Score 

\override MetronomeMark.extra-offset = #'(-5 . 0) 
\override MetronomeMark.padding = #'3 

> 

\context { 

\Staff 
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\override TimeSignature.style = #'numbered 

> 

\context { 

Woice 

\override Glissando.thickness = #3 
\override Glissando.gap = #0.1 

> 

> 


Clarinet! 
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mp dolce 


That looks nicer! But now suppose that I want to publish this piece. My composition 
professor doesn’t like ‘C’ time signatures, but I’m somewhat fond of them. Let’s copy the 
current ‘definitions. ily’ to ‘web-publish. ily’ and modify that. Since this music is aimed 
at producing a pdf which will be displayed on the screen, we’ll also increase the overall size of 
the output. 

TO web-publish.ily 
mpdolce = 

\tweak self-alignment-X #-0.6 
#(make-dynamic-script 

#{ \markup { \dynamic mp \normal-text \italic \bold dolce } #}) 


inst = 

#(define-music-function 

(parser location string) 

(string?) 

#{ <>~\markup \bold \box #string #}) 


#(set-global-staff-size 23) 


\layout-[ 

\context { 

\Score 

\override MetronomeMark.extra-offset = #'(-5 
\override MetronomeMark.padding = #'3 

> 

\context { 

\Staff 

> 

\context { 

Woice 

\override Glissando.thickness = #3 
\override Glissando.gap = #0.1 

> 

> 


0 ) 
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mp dolce 


Clarinet 
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Now in our music, I simply replace \include "definitions. ily" with \include 
"web-publish. ily". Of course, we could make this even more convenient. We could 
make a ‘definitions. ily’ file which contains only the definitions of mpdolce and inst, 
a ‘web-publish. ily’ file which contains only the \layout section listed above, and a 
‘university. ily’ file which contains only the tweaks to produce the output that my professor 
prefers. The top of ‘music.ly’ would then look like this: 

\include "definitions.ily" 

TO Only uncomment one of these two lines! 

\include "web-publish.ily" 

°/o\include "university. ily" 

This approach can be useful even if you are only producing one set of parts. I use half 
a dozen different ‘style sheet’ files for my projects. I begin every music file with \include 
". . /global. ily", which contains 

HZ. global, ily 
\version "2.18.2" 

#(ly:set-option 'point-and-click #f) 

\include "../init/init-defs.ly" 

\include "../init/init-layout.ly" 

\include "../init/init-headers.ly" 

\include "../init/init-paper.ly" 

4.7.4 Other sources of information 

The Internals Reference documentation contains a lot of information about LilyPond, but even 
more information can be gathered by looking at the internal LilyPond files. To explore these, you 
must first find the directory appropriate to your system. The location of this directory depends 
(a) on whether you obtained LilyPond by downloading a precompiled binary from lilypond.org or 
whether you installed it from a package manager (i.e. distributed with GNU/Linux, or installed 
under fink or cygwin) or compiled it from source, and (b) on which operating system it is being 
used: 

Downloaded from lilypond. org 

• GNU/Linux 
Navigate to 

‘ I]\fST4LLDIR/lilypond/usr/share/lilypond/current/ ’ 

• MacOS X 
Navigate to 

‘ Ii\fST4LLDIft/LilyPond. app/Contents/Resources/share/lilypond/current/ ’ 
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by either cd-ing into this directory from the Terminal, or control-clicking on the LilyPond 
application and selecting ‘Show Package Contents’. 

• Windows 

Using Windows Explorer, navigate to 

‘ Il\fST4LLDIft/LilyPond/usr/share/lilypond/current/ ’ 

Installed from, a package manager or compiled from source 

Navigate to ‘PfiEFIX/share/lilypond/X. Y.Z/\ where PREFIX is set by your package manager 
or configure script, and X.Y.Z is the LilyPond version number. 

Within this directory the two interesting subdirectories are 

• ‘ly/’ - contains files in LilyPond format 

• ‘scm/’ - contains files in Scheme format 

Let’s begin by looking at some files in Ty/’. Open Ty/property-init. ly’ in a text editor. 
The one you normally use for . ly files will be fine. This file contains the definitions of all the 
standard LilyPond predefined commands, such as \stemUp and \slurDotted. You will see that 
these are nothing more than definitions of variables containing one or a group of \override 
commands. For example, /tieDotted is defined to be: 
tieDotted = { 

\override Tie.dash-period = #0.75 
\override Tie.dash-fraction = #0.1 

> 

If you do not like the default values these predefined commands can be redefined easily, just 
like any other variable, at the head of your input file. 

The following are the most useful files to be found in ‘ly/’: 

Filename Contents 

‘ly/engraver-init. ly’ Definitions of engraver Contexts 

‘ly/paper-def aults-init. ly’ Specifications of paper-related defaults 

‘ly/perf ormer-init. ly’ Definitions of performer Contexts 

Ty/property-init. ly’ Definitions of all common predefined commands 

‘ly/spanner-init. ly’ Definitions of spanner-related predefined commands 

Other settings (such as the definitions of markup commands) are stored as ‘.scm’ (Scheme) 
files. The Scheme programming language is used to provide a programmable interface into 
LilyPond internal operation. Further explanation of these files is currently outside the scope of 
this manual, as a knowledge of the Scheme language is required. Users should be warned that a 
substantial amount of technical knowledge or time is required to understand Scheme and these 
files (see Section “Scheme tutorial” in Extending). 

If you have this knowledge, the Scheme files which may be of interest are: 


Filename 

‘scm/auto-beam.scm’ 

‘scm/define-grobs.scm' 

‘scm/define-markup-commands.scm’ 
‘scm/midi.scm' 

‘scm/output-lib.scm’ 

‘scm/parser-clef.scm’ 

‘scm/script.scm’ 


Contents 

Sub-beaming defaults 
Default settings for grob properties 
Specify all markup commands 
Default settings for MIDI output 

Settings that affect appearance of frets, colors, acciden¬ 
tals, bar lines, etc 
Definitions of supported clefs 
Default settings for articulations 
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4.7.5 Advanced tweaks with Scheme 


Although many things are possible with the \override and \tweak commands, an even more 
powerful way of modifying the action of LilyPond is available through a programmable interface 
to the LilyPond internal operation. Code written in the Scheme programming language can be 
incorporated directly in the internal operation of LilyPond. Of course, at least a basic knowledge 
of programming in Scheme is required to do this, and an introduction is provided in the Section 
“Scheme tutorial” in Extending. 

As an illustration of one of the many possibilities, instead of setting a property to a constant 
it can be set to a Scheme procedure which is then called whenever that property is accessed by 
LilyPond. The property can then be set dynamically to a value determined by the procedure at 
the time it is called. In this example we color the note head in accordance with its position on 
the staff. 


#(define (color—notehead grob) 

"Color the notehead according to its position on the staff." 

(let ((mod-position (modulo (ly:grob-property grob 1 staff-position) 

7))) 

(case mod-position 

;; Return rainbow colors 

C 
D 
E 
F 
G 
A 
B 


% Arrange to obtain color from color-notehead procedure 
\override NoteHead.color = #color-notehead 
a2 b | c2 d | e2 f | g2 a | 


((1) 

(xll-color 

' red 

)) 

for 

((2) 

(xll-color 

1 orange 

)) 

for 

((3) 

(xll-color 

'yellow 

)) 

for 

((4) 

(xll-color 

'green 

)) 

for 

((5) 

(xll-color 

'blue 

)) 

for 

((6) 

(xll-color 

'purple 

)) 

for 

((0) 

(xll-color 

'violet 

)) 

for 

))) 





ve c 

{ 






Further examples showing the use of these programmable interfaces can be found in Section 
Callback functions” in Extending. 
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Appendix A Templates 

This section of the manual contains templates with the LilyPond score already set up for you. 
Just add notes, run LilyPond, and enjoy beautiful printed scores! 

A.l Single staff templates 

A.1.1 Notes only 

This very simple template gives you a staff with notes, suitable for a solo instrument or a melodic 
fragment. Cut and paste this into a file, add notes, and you’re finished! 

\version "2.18.2" 
melody = \relative c 1 { 

\clef treble 
\key c \major 
\time 4/4 

a4 b c d 

> 

\score { 

\new Staff \melody 
\layout { } 

\midi { } 

} 



A. 1.2 Notes and lyrics 

This small template demonstrates a simple melody with lyrics. Cut and paste, add notes, then 
words for the lyrics. This example turns off automatic beaming, which is common for vocal 
parts. To use automatic beaming, change or comment out the relevant line. 

\version "2.18.2" 
melody = \relative c 1 { 

\clef treble 
\key c \major 
\time 4/4 

a4 b c d 

} 

text = \lyricmode { 

Aaa Bee Cee Dee 

} 

\score{ 

<< 

\new Voice = "one" { 

\autoBeamOff 
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\melody 

} 

\new Lyrics \lyricsto "one" \text 

» 

May out { } 

\midi { } 



A.1.3 Notes and chords 

Want to prepare a lead sheet with a melody and chords? Look no further! 

melody = \relative c 1 { 

\clef treble 
\key c \major 
\time 4/4 

f4 e8[ c] d4 g 
a2 ~ a 

} 

harmonies = \chordmode { 
c4:m f:min7 g:maj c:aug 
d2:dim b:sus 

> 

\score { 

<< 

\new ChordNames { 

\set chordChanges = ##t 
\harmonies 

} 

\new Staff \melody 

» 

\layout{ } 

\midi { } 

> 



A.1.4 Notes, lyrics, and chords 

This template allows the preparation of a song with melody, words, and chords. 

melody = \relative c 1 { 

\clef treble 
\key c \major 
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\time 4/4 
a4 b c d 

> 

text = \lyricmode { 

Aaa Bee Cee Dee 

> 

harmonies = \chordmode { 
a2 c 

> 

\score { 

<< 

\new ChordNames { 

\set chordChanges = ##t 
\harmonies 

} 

\new Voice = "one" { \autoBeamOff \melody } 
\new Lyrics \lyricsto "one" \text 

» 

\layout { } 

\midi { } 



A.2 Piano templates 
A.2.1 Solo piano 

Here is a simple piano staff with some notes. 

upper = \relative c 1 1 { 

\clef treble 
\key c \major 
\time 4/4 

a4 b c d 

} 

lower = \relative c { 

\clef bass 
\key c \major 
\time 4/4 


a2 c 


} 
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\score { 

\new PianoStaff « 

\set PianoStaff.instrumentName = #"Piano " 
\new Staff = "upper" \upper 
\new Staff = "lower" Mower 

» 

May out { } 

\midi { } 


Piano 



A.2.2 Piano and melody with lyrics 

Here is a typical song format: one staff with the melody and lyrics, with piano accompaniment 
underneath. 

melody = \relative c 1 ' { 

\clef treble 
\key c \major 
\time 4/4 

abed 

} 

text = Myricmode { 

Aaa Bee Cee Dee 

> 

upper = \relative c 11 { 

\clef treble 
\key c \major 
\time 4/4 

a4 b c d 

} 

lower = \relative c { 

\clef bass 
\key c \major 
\time 4/4 

a2 c 

> 

\score { 

« 

\new Voice = "mel" { \autoBeamQff \melody } 
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\new Lyrics \lyricsto mel \text 
\new PianoStaff << 

\new Staff = "upper" \upper 
\new Staff = "lower" \lower 

>> 

» 

May out { 

\context { \Staff \RemoveEmptyStaves } 

> 

\midi { } 











Aaa Bee Cee Dee 


C 


m • 


Me 


2 : 


A.2.3 Piano centered lyrics 

Instead of having a full staff for the melody and lyrics, lyrics can be centered between the staves 
of a piano staff. 

upper = \relative c 11 { 

\clef treble 
\key c \major 
\time 4/4 

a4 b c d 

} 

lower = \relative c { 

\clef bass 
\key c \major 
\time 4/4 

a2 c 

> 

text = \lyricmode { 

Aaa Bee Cee Dee 

> 

\score { 

\new GrandStaff << 

\new Staff = upper { \new Voice = "singer" \upper } 

\new Lyrics Myricsto "singer" \text 
\new Staff = lower { Mower } 


» 
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May out { 

\context { 

\GrandStaff 
\accepts "Lyrics" 

} 

\context { 

\Lyrics 

\consists "Bar_engraver" 

} 

> 

\midi { } 



A.3 String quartet templates 
A.3.1 String quartet 

This template demonstrates a simple string quartet. It also uses a \global section for time and 
key signatures 

global= { 

\time 4/4 
\key c \major 

} 

violinOne = \new Voice \relative c'' { 

\set Staff.instrumentName = #"Violin 1 " 

c2 d 
el 

\bar "| " 


violinTwo = \new Voice \relative c 11 { 

\set Staff.instrumentName = #"Violin 2 " 

g2 f 

el 

\bar " | " 

> 

viola = \new Voice \relative c' { 

\set Staff.instrumentName = #"Viola " 
\clef alto 
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e2 d 
cl 

\bar " | " 

> 

cello = \new Voice \relative c' { 

\set Staff.instrumentName = #"Cello " 
\clef bass 

c2 b 
al 

\bar " | " 

> 

\score { 

\new StaffGroup « 

\new Staff << \global \violinOne » 
\new Staff << \global \violinTwo » 
\new Staff << \global \viola >> 

\new Staff << \global \cello >> 

» 

May out { } 

\midi { } 

> 


Violin 1 


Violin 2 


Viola 


Cello 


A.3.2 String quartet parts 

The “String quartet template” snippet produces a nice string quartet, but what if you needed 
to print parts? This new template demonstrates how to use the \tag feature to easily split a 
piece into individual parts. 

You need to split this template into separate files; the filenames are contained in comments 
at the beginning of each file, piece. ly contains all the music definitions. The other files - 
score.ly, vnl.ly, vn2.1y, vla.ly, and vlc.ly - produce the appropriate part. 

Do not forget to remove specified comments when using separate hies! 

11111 piece. ly 
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11111 (This is the global definitions file) 

global= { 

\time 4/4 
\key c \major 

} 

Violinone = \new Voice { \relative c''{ 

\set Staff.instrumentName = #"Violin 1 " 

c2 d el 

\ Vvav' ii I 11 ~L"L 0 /...,,,,...,.^,....,. ...... ....... 

^ U n I | , j J Iq 'T* * T* * * T* T* *T' -T' T' 'T' * 'r *T* *T* *T* * "T* 'T' 'T' T* * ■T" 'T* * * 'r 'r 'r * “T 

Violintwo = \new Voice { \relative c''{ 

\set Staff.instrumentName = #"Violin 2 " 

g2 f el 

II I 11 T. ~l 0 /...,....,,.....,,....,.,..,...... 

^ U n l | # j J Jq *T* *T* T* < T' < T' T* T* "T~ "T* T- 'T' * T* 'T' 'T' - T‘ * 'r * 'r 'T' 'T" 'T* 'T* * * 'r 'T' X 'T* ■'T* “T 

Viola = \new Voice { \relative c' { 

\set Staff.instrumentName = #"Viola " 

\clef alto 

e2 d cl 

V'u.o’v' 11 I 11 T ~L 0 /...,....,,.....,,....,.,..,...... 

^ U Cl l | # j J /q 'T* ‘T* T* * * T* T* "T~ "T* T- 'T' * T* -T* 'T' 'T* "T* ■T' * 'T' T* •T" 'T* 'T* * * 'r X 'T* ■'T* “T 

Cello = \new Voice { \relative c' { 

\set Staff.instrumentName = #"Cello " 

\clef bass 

c2 b al 

(t ar I ■ 11 1 '(• ^ 't' ^ ^ "f* "f* '(• 

music = { 

« 

\tag #’score \tag #’vnl \new Staff { << \global Wiolinone >> } 

\tag #’score \tag #’vn2 \new Staff { << \global \Violintwo» } 

\tag #’score \tag #’vla \new Staff { << \global \Viola» } 

\tag #’score \tag #’vlc \new Staff { << \global \Cello» } 

» 

} 

T/l These are the other files you need to save on your computer 
11111 score.ly 

mil (This is the main file) 

HI uncomment the line below when using a separate file 
°/ 0 \include "piece.ly" 

#(set-global-staff-size 14) 

\score { 
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\new StaffGroup \keepWithTag #'score \music 
May out { } 

\midi { } 


Uncomment this block when using separate files 
11111 vnl.ly 

11111 (This is the Violin 1 part file) 

\include "piece.ly" 

\score { 

\keepWithTag #'vnl \music 
\layout { } 


inn vn2.i y 

ma (This is the Violin 2 part file) 

\include "piece.ly" 

\score { 

\keepWithTag #'vn2 \music 
\layout { } 


ran via.iy 

rail (This is the Viola part file) 

\include "piece.ly" 

\score { 

\keepWithTag #'vla \music 
\layout { } 


inn vie. i y 

inn (This is the Cello part file) 

\include "piece.ly" 

\score { 

\keepWithTag #'vlc \music 
\layout { } 
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Violin 1 


Violin 2 


Viola 


Cello 



—G- 


i* p 



Uf# 

_ Q _ 



A.4 Vocal ensembles templates 
A.4.1 SATB vocal score 

Here is a standard four-part SATB vocal score. With larger ensembles, it is often useful to include 
a section which is included in all parts. For example, the time signature and key signature are 
almost always the same for all parts. Like in the “Hymn” template, the four voices are regrouped 
on only two staves. 

\paper { 

top-system-spacing # 1 basic-distance = #10 
score-system-spacing #'basic-distance = #20 
system-system-spacing # 1 basic-distance = #20 
last-bottom-spacing # 1 basic-distance = #10 

} 

global = { 

\key c \major 
\time 4/4 

} 

sopMusic = \relative c' 1 { 
c4 c c8[( b)] c4 

} 

sopWords = \lyricmode { 
hi hi hi hi 

} 

altoMusic = \relative c 1 { 
e4 f d e 

> 

altoWords = \lyricmode { 
ha ha ha ha 

> 

tenorMusic = \relative c' { 
g4 a f g 

} 

tenorWords = \lyricmode { 
hu hu hu hu 

> 

bassMusic = \relative c { 
c4 c g c 

} 

bassWords = \lyricmode { 
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ho ho ho ho 

> 

\score { 

\new ChoirStaff « 

\new Lyrics = "sopranos" \with { 

*/. this is needed for lyrics above a staff 
\override VerticalAxisGroup.staff-affinity = #D0WN 

} 

\new Staff = "women" « 

\new Voice = "sopranos" { 

\voiceOne 

<< \global \sopMusic » 

> 

\new Voice = "altos" { 

\voiceTwo 

<< \global \altoMusic » 

> 

>> 

\new Lyrics = "altos" 

\new Lyrics = "tenors" \with { 

% this is needed for lyrics above a staff 
\override VerticalAxisGroup.staff-affinity = #D0WN 

} 

\new Staff = "men" « 

\clef bass 

\new Voice = "tenors" { 

\voiceOne 

<< \global \tenorMusic » 

> 

\new Voice = "basses" { 

\voiceTwo « \global \bassMusic » 

> 

>> 

\new Lyrics = "basses" 

\context Lyrics = "sopranos" \lyricsto "sopranos" \sopWords 
\context Lyrics = "altos" \lyricsto "altos" \altoWords 
\context Lyrics = "tenors" \lyricsto "tenors" \tenorWords 
\context Lyrics = "basses" \lyricsto "basses" \bassWords 


> 
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hi hi hi hi 



A.4.2 SATB vocal score and automatic piano reduction 

This template adds an automatic piano reduction to the standard SATB vocal score demon¬ 
strated in “Vocal ensemble template”. This demonstrates one of the strengths of LilyPond - 
you can use a music definition more than once. If any changes are made to the vocal notes (say, 
tenorMusic), then the changes will also apply to the piano reduction. 

\paper { 

top-system-spacing # 1 basic-distance = #10 
score-system-spacing #'basic-distance = #20 
system-system-spacing # 1 basic-distance = #20 
last-bottom-spacing # 1 basic-distance = #10 

} 

global = { 

\key c \major 
\time 4/4 

} 

sopMusic = \relative c' 1 { 
c4 c c8[( b)] c4 

} 

sopWords = \lyricmode { 
hi hi hi hi 

} 

altoMusic = \relative c 1 { 
e4 f d e 

> 

altoWords =\lyricmode { 
ha ha ha ha 

> 

tenorMusic = \relative c' { 
g4 a f g 

} 

tenorWords = \lyricmode { 
hu hu hu hu 

> 

bassMusic = \relative c { 
c4 c g c 

} 

bassWords = \lyricmode { 
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ho ho ho ho 

> 

\score { 

<< 

\new ChoirStaff << 

\new Lyrics = "sopranos" \with { 

*/. This is needed for lyrics above a staff 
\override VerticalAxisGroup.staff-affinity = #D0WN 

> 

\new Staff = "women" << 

\new Voice = "sopranos" { \voiceOne << \global \sopMusic » } 

\new Voice = "altos" { \voiceTwo << \global \altoMusic >> } 

>> 

\new Lyrics = "altos" 

\new Lyrics = "tenors" \with { 

*/. This is needed for lyrics above a staff 
\override VerticalAxisGroup.staff-affinity = #D0WN 

> 

\new Staff = "men" « 

\clef bass 

\new Voice = "tenors" { \voiceOne << \global \tenorMusic » } 

\new Voice = "basses" { \voiceTwo << \global \bassMusic >> } 

>> 

\new Lyrics = "basses" 

\context Lyrics = "sopranos" \lyricsto "sopranos" \sopWords 
\context Lyrics = "altos" \lyricsto "altos" \altoWords 
\context Lyrics = "tenors" \lyricsto "tenors" \tenorWords 
\context Lyrics = "basses" \lyricsto "basses" \bassWords 

>> 

\new PianoStaff << 

\new Staff « 

\set Staff.printPartCombineTexts = ##f 

\partcombine 

<< \global \sopMusic » 

« \global \altoMusic » 

>> 

\new Staff « 

\clef bass 

\set Staff.printPartCombineTexts = ##f 
\partcombine 

<< \global \tenorMusic » 

<< \global \bassMusic » 

>> 

>> 

» 


> 
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hi hi hi hi 



A.4.3 SATB with aligned contexts 

This template is basically the same as the simple “Vocal ensemble” template, with the exception 
that here all the lyrics lines are placed using alignAboveContext and alignBelowContext. 

global = { 

\key c \major 
\time 4/4 

> 

sopMusic = \relative c' 1 { 
c4 c c8[( b)] c4 

> 

sopWords = \lyricmode { 
hi hi hi hi 

> 

altoMusic = \relative c 1 { 
e4 f d e 

> 

altoWords = \lyricmode { 
ha ha ha ha 

> 

tenorMusic = \relative c 1 { 
g4 a f g 

> 

tenorWords = \lyricmode { 
hu hu hu hu 

> 

bassMusic = \relative c { 
c4 c g c 

> 

bassWords = \lyricmode { 
ho ho ho ho 


> 
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\score { 

\new ChoirStaff « 

\new Staff = "women" « 

\new Voice = "sopranos" { \voiceOne << \global \sopMusic >> } 
\new Voice = "altos" { \voiceTwo « \global \altoMusic » } 

>> 

\new Lyrics \with { alignAboveContext = #"women" } 

\lyricsto "sopranos" \sopWords 
\new Lyrics \with { alignBelowContext = #"women" } 

\lyricsto "altos" \altoWords 

% we could remove the line about this with the line below, since 
°/ 0 we want the alto lyrics to be below the alto Voice anyway. 

°/ 0 \new Lyrics \lyricsto "altos" \altoWords 

\new Staff = "men" « 

\clef bass 

\new Voice = "tenors" { \voice0ne « \global \tenorMusic >> } 
\new Voice = "basses" { \voiceTwo « \global \bassMusic » } 

>> 

\new Lyrics \with { alignAboveContext = #"men" } 

\lyricsto "tenors" \tenorWords 
\new Lyrics \with { alignBelowContext = #"men" } 

\lyricsto "basses" \bassWords 

°/ 0 again, we could replace the line above this with the line below. 
°/ 0 \new Lyrics \lyricsto "basses" \bassWords 

» 

> 


hi hi hi hi 



A.4.4 SATB on four staves 

SATB choir template (four staves) 

global = { 

\key c \major 
\time 4/4 
\dynamicUp 

} 

sopranonotes = \relative c 11 { 
c2 \p \< d c d \f 

} 

sopranowords = \lyricmode { do do do do } 
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altonotes = \relative c 11 { 
c2\p d c d 

} 

altowords = \lyricmode { re re re re } 
tenornotes = { 

\clef "G_8" 
c2\mp d c d 

} 

tenorwords = \lyricmode { mi mi mi mi } 
bassnotes = { 

\clef bass 
c2\mf d c d 

} 

basswords = \lyricmode { mi mi mi mi } 

\score { 

\new ChoirStaff « 

\new Staff << 

\new Voice = "soprano" << 

\global 

\sopranonotes 

>> 

\lyricsto "soprano" \new Lyrics \sopranowords 

>> 

\new Staff << 

\new Voice = "alto" << 

\global 

\altonotes 

>> 

\lyricsto "alto" \new Lyrics \altowords 

>> 

\new Staff << 

\new Voice = "tenor" << 

\global 

\tenornotes 

>> 

\lyricsto "tenor" \new Lyrics \tenorwords 

>> 

\new Staff << 

\new Voice = "bass" << 

\global 

\bassnotes 

>> 

\lyricsto "bass" \new Lyrics \basswords 

>> 

» 


> 
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A.4.5 Solo verse and two-part refrain 

This template creates a score which starts with a solo verse and continues into a refrain for two 
voices. It also demonstrates the use of spacer rests within the \global variable to define meter 
changes (and other elements common to all parts) throughout the entire score. 

global = { 

\key g \major 

% verse 
\time 3/4 
s2.*2 
\break 

% refrain 
\time 2/4 
s2*2 

\bar "|" 

> 

SoloNotes = \relative g 1 { 

\clef "treble" 

7o verse 
g4 g g I 
b4 b b | 

7o refrain 
R2*2 | 

> 

SoloLyrics = \lyricmode { 

One two three | 
four five six | 

} 


SopranoNotes = \relative c 11 { 
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\clef "treble" 

% verse 
R2.*2 | 

% refrain 
c4 c I 
g4 g I 

> 

SopranoLyrics = \lyricmode { 
la la | 
la la | 


BassNotes = \relative c { 

\clef "bass" 

7o verse 
R2.*2 | 

7o refrain 
c4 e I 
d4 d | 

> 

BassLyrics = \lyricmode { 
dum dum | 
dum dum | 

> 

\score { 

« 

\new Voice = "SoloVoice" << \global \SoloNotes » 

\new Lyrics \lyricsto "SoloVoice" \SoloLyrics 

\new ChoirStaff << 

\new Voice = "SopranoVoice" << \global \SopranoNotes » 
\new Lyrics \lyricsto "SopranoVoice" \SopranoLyrics 

\new Voice = "BassVoice" « \global \BassNotes » 

\new Lyrics \lyricsto "BassVoice" \BassLyrics 

>> 

» 

\layout { 

ragged-right = ##t 
\context { \Staff 

7» these lines prevent empty staves from being printed 
\RemoveEmptyStaves 

\override VerticalAxisGroup.remove-first = ##t 

} 

> 



Appendix A: Templates 


164 


> 



One two three four five six 



dum dum dum dum 


A.4.6 Hymn tunes 

This code shows one way of setting out a hymn tune when each line starts and ends with a 
partial measure. It also shows how to add the verses as stand-alone text under the music. 

Timeline = { 

\time 4/4 
\tempo 4=96 
\partial 2 

s2 | si | s2 \breathe s2 | si | s2 \bar "II" \break 

s2 | si | s2 \breathe s2 | si | s2 \bar "II" 

} 

SopranoMusic = \relative g 1 { 

g4g|gggg|gggg|gggg|g2 

g4g|gggg|gggg|gggg|g2 

> 

AltoMusic = \relative c 1 { 

d4d | dddd | dddd | dddd | d2 

d4d | dddd | dddd | dddd | d2 


TenorMusic = \relative a { 

b4b | bbbb | bbbb | bbbb | b2 
b4b I bbbb | bbbb | bbbb | b2 


BassMusic = \relative g { 

g4g I gggg I gggg I gggg I g2 
g4g I gggg I gggg I gggg I g2 

} 

global = { 

\key g \major 

> 


\score { % Start score 
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<< 

\new PianoStaff << % Start pianostaff 

\new Staff « % Start Staff = RH 

\global 

\clef "treble" 

\new Voice = "Soprano" « % Start Voice = "Soprano" 

\Timeline 
\voiceOne 
\SopranoMusic 

» °/ 0 End Voice = "Soprano" 

\new Voice = "Alto" << % Start Voice = "Alto" 

\Timeline 
\voiceTwo 
\AltoMusic 

» 7, End Voice = "Alto" 

» l End Staff = RH 
\new Staff « 7 0 Start Staff = LH 

\global 
\clef "bass" 

\new Voice = "Tenor" << 7o Start Voice = "Tenor" 
\Timeline 
\voiceOne 
\TenorMusic 

» % End Voice = "Tenor" 

\new Voice = "Bass" << 7o Start Voice = "Bass" 
\Timeline 
\voiceTwo 
\BassMusic 

» % End Voice = "Bass" 

» l End Staff = LH 
>> 7o End pianostaff 

» 

} 1 End score 

\markup { 

\fill-line { 

II II 

{ 

\column { 

\left-align { 

"This is line one of the first verse" 

"This is line two of the same" 

"And here's line three of the first verse" 

"And the last line of the same" 

} 

> 

} 


> 


> 


\paper { 7„ Start paper block 
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indent = 0 % don't indent first system 

line-width = 130 % shorten line length to suit music 

} 7» End paper block 


It 


J. 


96 


E 


a 


m 


w 


m 


i 




am 

3 

H 

3 

MW 

3 

ffi 

5 

■Sii 


|»jg 










This is line one of the first verse 
This is line two of the same 
And here's line three of the first verse 
And the last line of the same 


A.4.7 Psalms 

This template shows one way of setting out an Anglican psalm chant. It also shows how the 
verses may be added as stand-alone text under the music. The two verses are coded in different 
styles to demonstrate more possibilities. 

SopranoMusic = \relative g 1 { 
gl I c2 b | al | \bar "||" 
al | d2 c | c b | cl | \bar "II" 

} 

AltoMusic = \relative c 1 { 
el | g2 g | fl | 
fl I f2 e | d d | el | 

> 

TenorMusic = \relative a { 
cl I c2 c | cl | 

dl I g,2 g I g g I gl I 

} 

BassMusic = \relative c { 
cl I e2 e | fl | 
dl | b2 c | g 1 g | c,l | 

> 

global = { 

\time 2/2 

> 
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dot = \markup { 

\raise #0.7 \musicglyph #"dots.dot" 

> 

tick = \markup { 

\raise #1 \fontsize #-5 \musicglyph #"scripts.rvarcomma" 

> 


l Use markup to center the chant on the page 
\markup { 

\fill-line { 

\score { ”/„ centered 

<< 

\new ChoirStaff « 

\new Staff << 

\global 

\clef "treble" 

\new Voice = "Soprano" << 

\voice0ne 

\SopranoMusic 

>> 

\new Voice = "Alto" « 

\voiceTwo 

\AltoMusic 

>> 

» 

\new Staff << 

\clef "bass" 

\global 

\new Voice = "Tenor" << 

\voice0ne 

\TenorMusic 

>> 

\new Voice = "Bass" « 

\voiceTwo 

\BassMusic 

>> 

» 

>> 

>> 

\layout { 

\context { 

\Score 

\override SpacingSpanner.base-shortest-duration = #(ly:make-moment 1/2) 

> 

\context { 

\Staff 

\remove "Time_signature_engraver" 

} 

> 

} % End score 
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> 

} 7. End markup 

\markup { 

\fill-line { 

\column { 

\left-align { 

\null \null \null 
Mine { 

\fontsize #5 0 
\fontsize #3 come 

let us \bold sing | unto \dot the | Lord : let 

> 

Mine { 

us heartily 

\concat { re \bold joice } 
in the | strength of | our 

> 

Mine { 

sal I vation. 

> 

\null 
Mine { 

\hspace #2.5 8. Today if ye will hear his voice * 

} 

Mine { 

\concat { \bold hard en } 

\tick not your \tick hearts : as in the pro- 

} 

Mine { 

vocation * and as in the \bold day of tempt- \tick 

} 

Mine { 

-ation \tick in the \tick wilderness. 

} 

> 

} 

> 

> 












Appendix A: Templates 


169 


O come let us sing I unto • the I Lord : let 
us heartily rejoice in the I strength of I our 
sal I vation. 

8. Today if ye will hear his voice * 
harden ' not your ' hearts : as in the pro¬ 
vocation * and as in the day of tempt-' 

-ation ' in the ' wilderness. 

A.5 Orchestral templates 
A.5.1 Orchestra, choir and piano 

This template demonstrates the use of nested Staff Group and GrandStaff contexts to sub¬ 
group instruments of the same type together, and a way to use \transpose so that variables 
hold music for transposing instruments at concert pitch. 

#(set-global-staff-size 17) 

\paper { 

indent = 3.0\cm °/ 0 space for instrumentName 

short-indent = 1.5\cm % space for shortInstrumentName 

> 

fluteMusic = \relative c 1 { \key g \major g'l b } 
l Pitches as written on a manuscript for Clarinet in A 
*/. are transposed to concert pitch. 
clarinetMusic = \transpose c' a 

\relative c 11 { \key bes \major besl d } 
trumpetMusic = \relative c { \key g \major g''1 b } 

% Key signature is often omitted for horns 
hornMusic = \transpose c' f 
\relative c { d'l fis } 

percussionMusic = \relative c { \key g \major gl b } 
sopranoMusic = \relative c 11 { \key g \major g'l b } 
sopranoLyrics = \lyricmode { Lyr — ics } 
altoIMusic = \relative c' { \key g \major g'l b } 
altoIIMusic = \relative c' { \key g \major g'l b } 
altoILyrics = \sopranoLyrics 
altoIILyrics = \lyricmode { Ah — ah } 

tenorMusic = \relative c' { \clef "treble_8" \key g \major gl b } 
tenorLyrics = \sopranoLyrics 

pianoRHMusic = \relative c { \key g \major g''1 b } 
pianoLHMusic = \relative c { \clef bass \key g \major gl b } 
violinIMusic = \relative c' { \key g \major g'l b } 
violinllMusic = \relative c' { \key g \major g'l b } 
violaMusic = \relative c { \clef alto \key g \major g'l b } 
celloMusic = \relative c { \clef bass \key g \major gl b } 
bassMusic = \relative c { \clef "bass_8" \key g \major g,l b } 

\score { 

« 

\new StaffGroup = "StaffGroup_woodwinds" « 
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\new Staff = "Staff_flute" { 

\set Staff.instrumentName = #"Flute" 
l shortInstrumentName, midiInstrument, etc. 

*/. may be set here as well 
\fluteMusic 

> 

\new Staff = "Staff_clarinet" { 

\set Staff.instrumentName = 

\markup { \concat { "Clarinet in B" \flat } } 

*/. Declare that written Middle C in the music 
*/. to follow sounds a concert B flat, for 
l output using sounded pitches such as MIDI. 
\transposition bes 

*/. Print music for a B-flat clarinet 
\transpose bes c' \clarinetMusic 

> 

>> 

\new StaffGroup = "StaffGroup_brass" << 

\new Staff = "Staff_hornI" { 

\set Staff.instrumentName = #"Horn in F" 
\transposition f 
\transpose f c' \hornMusic 

> 

\new Staff = "Staff_trumpet" { 

\set Staff.instrumentName = #"Trumpet in C" 
\trumpetMusic 

> 

>> 

\new RhythmicStaff = "RhythmicStaff_percussion" << 
\set RhythmicStaff.instrumentName = #"Percussion" 
\percussionMusic 

>> 

\new PianoStaff << 

\set PianoStaff.instrumentName = #"Piano" 

\new Staff { \pianoRHMusic } 

\new Staff { \pianoLHMusic } 

>> 

\new ChoirStaff = "ChoirStaff_choir" << 

\new Staff = "Staff_soprano" { 

\set Staff.instrumentName = #"Soprano" 

\new Voice = "soprano" 

\sopranoMusic 

> 

\new Lyrics \lyricsto "soprano" { \sopranoLyrics } 
\new GrandStaff = "GrandStaff_altos" 

\with { \accepts Lyrics } « 

\new Staff = "Staff_altoI" { 

\set Staff.instrumentName = #"Alto I" 

\new Voice = "altol" 

\altoIMusic 

> 

\new Lyrics \lyricsto "altol" { \altoILyrics } 
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\new Staff = "Staff_altoII" { 

\set Staff.instrumentName = #"Alto II" 

\new Voice = "altoll" 

\altoIIMusic 

} 

\new Lyrics \lyricsto "altoll" { \altoIILyrics } 

>> 

\new Staff = "Staff_tenor" { 

\set Staff.instrumentName = #"Tenor" 

\new Voice = "tenor" 

\tenorMusic 

> 

\new Lyrics \lyricsto "tenor" { \tenorLyrics } 

>> 

\new StaffGroup = "StaffGroup_strings" << 

\new GrandStaff = "GrandStaff_violins" « 

\new Staff = "Staff_violinI" { 

\set Staff.instrumentName = #"Violin I" 
\violinIMusic 

> 

\new Staff = "Staff_violinII" { 

\set Staff.instrumentName = #"Violin II" 
\violinIIMusic 

> 

>> 

\new Staff = "Staff_viola" { 

\set Staff.instrumentName = #"Viola" 

\violaMusic 

> 

\new Staff = "Staff_cello" { 

\set Staff.instrumentName = #"Cello" 

\celloMusic 

> 

\new Staff = "Staff_bass" { 

\set Staff.instrumentName = #"Double Bass" 
\bassMusic 

> 

>> 

» 

\layout { } 

} 
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Flute 

Clarinet in B[> 
Horn in F 
Trumpet in C 
Percussion 

Piano 

Soprano 
Alto I 

Alto II 

Tenor 

Violin I 

Violin II 

Viola 

Cello 

Double Bass 



A.6 Ancient notation templates 
A.6.1 Transcription of mensural music 

When transcribing mensural music, an incipit at the beginning of the piece is useful to indicate 
the original key and tempo. While today musicians are used to bar lines in order to faster 
recognize rhythmic patterns, bar lines were not yet invented during the period of mensural 
music; in fact, the meter often changed after every few notes. As a compromise, bar lines are 
often printed between the staves rather than on the staves. 

global = { 

\set Score.skipBars = ##t 
% incipit 

\once \hide Score.SystemStartBracket 
% Set tight spacing 

\override Score.SpacingSpanner.spacing-increment = #1.0 
\key f \major 
\time 2/2 

\once \override Staff.TimeSignature.style = # 1 neomensural 
\override Voice.NoteHead.style = #'neomensural 
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\override Voice.Rest.style = # 1 neomensural 
\set Staff.printKeyCancellation = ##f 
\cadenzaOn % turn off bar lines 
\skip 1*10 

\once \override Staff.BarLine.transparent = ##f 
\bar "II" 

\skip 1*1 °/ 0 need this extra \skip such that clef change comes 
7, after bar line 

\bar "" 

% main 

\cadenzaOff % turn bar lines on again 

\once \override Staff.Clef.full-size-change = ##t 

\set Staff.forceClef = ##t 

\key g \major 

\time 4/4 

\override Voice.NoteHead.style = #'default 
\override Voice.Rest.style = #'default 

% Setting printKeyCancellation back to #t must not 

7o occur in the first bar after the incipit. Dto. for forceClef. 

7o Therefore, we need an extra \skip. 

\skip 1*1 

\set Staff.printKeyCancellation = ##t 
\set Staff.forceClef = ##f 

\skip 1*7 7. the actual music 

7o let finis bar go through all staves 
\override Staff.BarLine.transparent = ##f 

7o finis bar 
\bar " | . " 

> 

discantusNotes = { 

\transpose c' c 11 { 

\set Staff.instrumentName = #"Discantus " 

7o incipit 

\clef "neomensural-cl" 
c 1 1. s2 7» two bars 
\skip 1*8 7. eight bars 
\skip 1*1 7» one bar 

7o main 

\clef "treble" 
d'2. d 1 4 I 
b e' d'2 | 

c 1 4 e 1 4. ( d 1 8 c’ b | 

a4) b a2 | 

b4.( c 1 8 d'4) c 1 4 | 
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\once \hide NoteHead c 1 1 | 
b\breve | 

> 

> 

discantusLyrics = \lyricmode { 
% incipit 
IV- 


% main 

Ju — bi — I 
la — te De — I 
o, om — 
nis ter — I 
ra, _ om- | 


-us. | 

> 

altusNotes = { 

\transpose c' c 11 { 

\set Staff.instrumentName = # 

7o incipit 

\clef "neomensural-c3" 
rl 7. one bar 

fl. s2 7» two bars 
\skip 1*7 7» seven bars 
\skip 1*1 7» one bar 

7o main 

\clef "treble" 

r2 g2. e4 fis g | 7o two bars 
a2 g4 e | 

fis g4.( fisl6 e fis4) | 

gl I 

\once \hide NoteHead gl | 
g\breve | 

> 

} 

altusLyrics = \lyricmode { 

7o incipit 
IV- 

7o main 

Ju — bi — la — te | 

De — o, om — I 
nis ter — ra, | 


-us. | 

} 


"Altus " 


7o two bars 
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tenorNotes = { 

\transpose c' c' { 

\set Staff.instrumentName = #"Tenor " 

°/ 0 incipit 

\clef "neomensural-c4" 
r\longa ”/„ four bars 
r\breve ”/„ two bars 
rl ”/„ one bar 

c 1 1. s2 ”/„ two bars 
\skip 1*1 ”/„ one bar 
\skip 1*1 */. one bar 

°/ 0 main 

\clef "treble_8" 

Rl | 

Rl | 

Rl I 

r2 d'2. d'4 b e 1 | % two bars 
\once \hide NoteHead e 1 1 | 
d'\breve | 

> 

} 

tenorLyrics = \lyricmode { 

% incipit 
IV- 

% main 

Ju — bi — la — te | % two bars 

II II | 

-us. I 

} 

bassusNotes = { 

\transpose c 1 c' { 

\set Staff.instrumentName = #"Bassus " 

7o incipit 
\clef "bass" 
r\maxima °l eight bars 
fl. s2 7. two bars 
\skip 1*1 7» one bar 

7o main 
\clef "bass" 

Rl I 
Rl | 

Rl I 
Rl | 

g2. e4 | 
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\once \hide NoteHead el | 
g\breve | 

> 

> 

bassusLyrics = \lyricmode { 

% incipit 
IV- 


% main 
Ju — bi- | 

II II | 

-us. | 

> 

\score { 

\new StaffGroup = choirStaff « 

\new Voice = 

"discantusNotes" « \global \discantusNotes >> 

\new Lyrics = 

"discantusLyrics" \lyricsto discantusNotes { \discantusLyrics } 
\new Voice = 

"altusNotes" << \global \altusNotes >> 

\new Lyrics = 

"altusLyrics" \lyricsto altusNotes { \altusLyrics } 

\new Voice = 

"tenorNotes" << \global \tenorNotes >> 

\new Lyrics = 

"tenorLyrics" \lyricsto tenorNotes { \tenorLyrics } 

\new Voice = 

"bassusNotes" << \global \bassusNotes » 

\new Lyrics = 

"bassusLyrics" \lyricsto bassusNotes { \bassusLyrics } 

» 

May out { 

\context { 

\Score 

7» no bars in staves 
\hide BarLine 

7» incipit should not start with a start delimiter 
\remove "System_start_delimiter_engraver" 

} 

\context { 

Woice 

7» no slurs 
\hide Slur 

7» The command below can be commented out in 
7. short scores, but especially for large scores you 
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A.6.2 Gregorian transcription template 

This example demonstrates how to do modern transcription of Gregorian music. Gregorian 
music has no measure, no stems; it uses only half and quarter note heads, and special marks, 
indicating rests of different length. 

\include "gregorian.ly" 

chant = \relative c 1 { 

\set Score.timing = ##f 
f4 a2 \divisioMinima 
g4 b a2 f2 \divisioMaior 
g4( f) f( g) a2 \finalis 

> 

verba = \lyricmode { 

Lo — rem ip — sum do — lor sit a — met 

> 

\score { 

\new Staff << 

\new Voice = "melody" \chant 

\new Lyrics = "one" \lyricsto melody \verba 

» 

\layout { 

\context { 

\Staff 

\remove "Time_signature_engraver" 

\remove "Bar_engraver" 

\hide Stem 

} 

\context { 

Woice 

\override Stem.length = #0 

} 

\context { 

\Score 

barAlways = ##t 

} 

> 

> 



Lorem ip sum dolor sit a-met 


A.7 Other templates 
A.7.1 Jazz combo 

This is quite an advanced template, for a jazz ensemble. Note that all instruments are notated in 
\key c \major. This refers to the key in concert pitch; the key will be automatically transposed 
if the music is within a \transpose section. 
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\header { 

title = "Song" 
subtitle = "(tune)" 
composer = "Me" 
meter = "moderato" 
piece = "Swing" 
tagline = \markup { 

\column { 

"LilyPond example file by Amelie Zapf," 
"Berlin 07/07/2003" 


} 


> 


> 


°/ 0 #(set-global-staf f-size 16) 
\include "english.ly" 


UUUIUUI Some macros UIUUUIUUUU1 


si = { 

\override NoteHead.style = #'slash 
\hide Stem 

> 

nsl = { 

\revert NoteHead.style 
\undo \hide Stem 

> 

crOn = \override NoteHead.style = #'cross 
crOff = \revert NoteHead.style 

U insert chord name style stuff here. 


jazzChords = { } 
nimiUUl Keys 1 n' thangs 
global = { \time 4/4 } 

Key = { \key c \major } 


o, y y y y.I y y y y y o ,.I y y y y 
/o /o /o 10 /o /o /o 10 /o /o 10 /o /o /o 10 /o /o 


7o ############ Horns ############ 


%-Triimpet- 

trpt = \transpose c d \relative c 11 { 
\Key 

cl | c | c | 

> 

trpHarmony = \transpose c' d { 

\jazzChords 

> 

trumpet = { 

\global 
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\set Staff.instrumentName = #"Trumpet" 
\clef treble 
« 

\trpt 

» 

} 


*/.-Alto Saxophone- 

alto = \transpose c a \relative c' { 

\Key 

cl | c | c | 

> 

altoHarmony = \transpose c 1 a { 
\jazzChords 

> 

altoSax = { 

\global 

\set Staff.instrumentName = #"Alto Sax" 
\clef treble 
« 

\alto 

» 

} 


l - Baritone Saxophone - 

bari = \transpose c a' \relative c { 

\Key 

cl 

cl 

\sl 

d4~"Solo" d d d 
\nsl 

} 

bariHarmony = \transpose c 1 a \chordmode { 
\jazzChords si s d2:maj e:m7 

} 

bariSax = { 

\global 

\set Staff.instrumentName = #"Bari Sax" 
\clef treble 
<< 

\bari 

» 

> 


l - Trombone - 

tbone = \relative c { 

\Key 

cl | c | c 

} 

tboneHarmony = \chordmode { 
\jazzChords 
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trombone = { 

\global 

\set Staff.instrumentName = #"Trombone" 
\clef bass 
« 

\tbone 

» 

> 

7 . ############ Rhythm Section ############# 

7,-Guitar- 

gtr = \relative c 11 { 

\Key 

cl 

\sl 

b4 b b b 

\nsl 

cl 

> 

gtrHarmony = \chordmode { 

\jazzChords 
si c2:min7+ d2:maj9 

> 

guitar = { 

\global 

\set Staff.instrumentName = #"Guitar" 
\clef treble 
« 

\gtr 

» 

} 


7 o 7 o -Piano- 

rhUpper = \relative c 1 1 { 
\voiceOne 
\Key 

cl | c | c 

} 

rhLower = \relative c 1 { 
\voiceTwo 
\Key 

el | e | e 

> 

lhUpper = \relative c' { 
\voiceOne 
\Key 

gl I g I g 

> 

lhLower = \relative c { 
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\voiceTwo 

\Key 

cl | c | c 


PianoRH = { 

\clef treble 
\global 

\set Staff.midiinstrument = #"acoustic grand" 

« 

\new Voice = "one" \rhUpper 
\new Voice = "two" \rhLower 

» 

> 

PianoLH = { 

\clef bass 
\global 

\set Staff.midiinstrument = #"acoustic grand" 

« 

\new Voice = "one" \lhUpper 
\new Voice = "two" \lhLower 

» 

> 

piano = { 

<< 

\set PianoStaff.instrumentName = #"Piano" 
\new Staff = "upper" \PianoRH 
\new Staff = "lower" \PianoLH 

» 

> 


l -Bass Guitar- 

Bass = \relative c { 

\Key 

cl I c | c 

> 

bass = { 

\global 

\set Staff.instrumentName = #"Bass" 
\clef bass 
« 

\Bass 

» 

> 


% - Drums - 

up = \drummode { 
\voiceOne 

hh4 <hh sn> hh <hh sn> 
hh4 <hh sn> hh <hh sn> 
hh4 <hh sn> hh <hh sn> 
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> 

down = \drummode { 

\voiceTwo 
bd4 s bd s 
bd4 s bd s 
bd4 s bd s 

> 

drumContents = { 

\global 

« 

\set DrumStaff.instrumentName = #"Drums" 
\new DrumVoice \up 
\new DrumVoice \down 

» 

} 


nnnr/X It All Goes Together Here H \UUIUUUIUUUU 


\score { 

« 

\new StaffGroup = "horns" << 

\new Staff = "trumpet" \trumpet 

\new Staff = "altosax" \altoSax 

\new ChordNames = "barichords" \bariHarmony 

\new Staff = "barisax" \bariSax 

\new Staff = "trombone" \trombone 


\new StaffGroup = "rhythm" « 

\new ChordNames = "chords" \gtrHarmony 
\new Staff = "guitar" \guitar 
\new PianoStaff = "piano" \piano 
\new Staff = "bass" \bass 
\new DrumStaff \drumContents 

>> 

» 

May out { 

\context { \Staff \RemoveEmptyStaves } 
\context { 

\Score 

\override BarNumber.padding = #3 
\override RehearsalMark.padding = #2 
skipBars = ##t 

} 

> 

\midi { } 
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Song 

(tune) 


Swing 
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Appendix B GNU Free Documentation License 

Version 1.3, 3 November 2008 

Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. 
http://fsf.org/ 

Everyone is permitted to copy and distribute verbatim copies 
of this license document, but changing it is not allowed. 

0. PREAMBLE 

The purpose of this License is to make a manual, textbook, or other functional and useful 
document free in the sense of freedom: to assure everyone the effective freedom to copy 
and redistribute it, with or without modifying it, either commercially or noncommercially. 
Secondarily, this License preserves for the author and publisher a way to get credit for their 
work, while not being considered responsible for modifications made by others. 

This License is a kind of “copyleft”, which means that derivative works of the document 
must themselves be free in the same sense. It complements the GNU General Public License, 
which is a copyleft license designed for free software. 

We have designed this License in order to use it for manuals for free software, because free 
software needs free documentation: a free program should come with manuals providing the 
same freedoms that the software does. But this License is not limited to software manuals; 
it can be used for any textual work, regardless of subject matter or whether it is published 
as a printed book. We recommend this License principally for works whose purpose is 
instruction or reference. 

1. APPLICABILITY AND DEFINITIONS 

This License applies to any manual or other work, in any medium, that contains a notice 
placed by the copyright holder saying it can be distributed under the terms of this License. 
Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that 
work under the conditions stated herein. The “Document”, below, refers to any such manual 
or work. Any member of the public is a licensee, and is addressed as “you”. You accept 
the license if you copy, modify or distribute the work in a way requiring permission under 
copyright law. 

A “Modified Version” of the Document means any work containing the Document or a 
portion of it, either copied verbatim, or with modifications and/or translated into another 
language. 

A “Secondary Section” is a named appendix or a front-matter section of the Document 
that deals exclusively with the relationship of the publishers or authors of the Document 
to the Document’s overall subject (or to related matters) and contains nothing that could 
fall directly within that overall subject. (Thus, if the Document is in part a textbook of 
mathematics, a Secondary Section may not explain any mathematics.) The relationship 
could be a matter of historical connection with the subject or with related matters, or of 
legal, commercial, philosophical, ethical or political position regarding them. 

The “Invariant Sections” are certain Secondary Sections whose titles are designated, as 
being those of Invariant Sections, in the notice that says that the Document is released 
under this License. If a section does not fit the above definition of Secondary then it is not 
allowed to be designated as Invariant. The Document may contain zero Invariant Sections. 
If the Document does not identify any Invariant Sections then there are none. 

The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or 
Back-Cover Texts, in the notice that says that the Document is released under this License. 
A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 
words. 
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A “Transparent” copy of the Document means a machine-readable copy, represented in a 
format whose specification is available to the general public, that is suitable for revising 
the document straightforwardly with generic text editors or (for images composed of pixels) 
generic paint programs or (for drawings) some widely available drawing editor, and that is 
suitable for input to text formatters or for automatic translation to a variety of formats 
suitable for input to text formatters. A copy made in an otherwise Transparent file format 
whose markup, or absence of markup, has been arranged to thwart or discourage subsequent 
modification by readers is not Transparent. An image format is not Transparent if used for 
any substantial amount of text. A copy that is not “Transparent” is called “Opaque”. 
Examples of suitable formats for Transparent copies include plain ascii without markup, 
Texinfo input format, LaTf^X input format, SGML or XML using a publicly available DTD, 
and standard-conforming simple HTML, PostScript or PDF designed for human modifica¬ 
tion. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats 
include proprietary formats that can be read and edited only by proprietary word proces¬ 
sors, SGML or XML for which the DTD and/or processing tools are not generally available, 
and the machine-generated HTML, PostScript or PDF produced by some word processors 
for output purposes only. 

The “Title Page” means, for a printed book, the title page itself, plus such following pages 
as are needed to hold, legibly, the material this License requires to appear in the title page. 
For works in formats which do not have any title page as such, “Title Page” means the 
text near the most prominent appearance of the work’s title, preceding the beginning of the 
body of the text. 

The “publisher” means any person or entity that distributes copies of the Document to the 
public. 

A section “Entitled XYZ” means a named subunit of the Document whose title either 
is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in 
another language. (Here XYZ stands for a specific section name mentioned below, such 
as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the 
Title” of such a section when you modify the Document means that it remains a section 
“Entitled XYZ” according to this definition. 

The Document may include Warranty Disclaimers next to the notice which states that 
this License applies to the Document. These Warranty Disclaimers are considered to be 
included by reference in this License, but only as regards disclaiming warranties: any other 
implication that these Warranty Disclaimers may have is void and has no effect on the 
meaning of this License. 

2. VERBATIM COPYING 

You may copy and distribute the Document in any medium, either commercially or noncom- 
mercially, provided that this License, the copyright notices, and the license notice saying 
this License applies to the Document are reproduced in all copies, and that you add no 
other conditions whatsoever to those of this License. You may not use technical measures 
to obstruct or control the reading or further copying of the copies you make or distribute. 
However, you may accept compensation in exchange for copies. If you distribute a large 
enough number of copies you must also follow the conditions in section 3. 

You may also lend copies, under the same conditions stated above, and you may publicly 
display copies. 

3. COPYING IN QUANTITY 

If you publish printed copies (or copies in media that commonly have printed covers) of the 
Document, numbering more than 100, and the Document’s license notice requires Cover 
Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover 
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both 
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covers must also clearly and legibly identify you as the publisher of these copies. The front 
cover must present the full title with all words of the title equally prominent and visible. 
You may add other material on the covers in addition. Copying with changes limited to 
the covers, as long as they preserve the title of the Document and satisfy these conditions, 
can be treated as verbatim copying in other respects. 

If the required texts for either cover are too voluminous to fit legibly, you should put the 
first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto 
adjacent pages. 

If you publish or distribute Opaque copies of the Document numbering more than 100, you 
must either include a machine-readable Transparent copy along with each Opaque copy, 
or state in or with each Opaque copy a computer-network location from which the general 
network-using public has access to download using public-standard network protocols a 
complete Transparent copy of the Document, free of added material. If you use the latter 
option, you must take reasonably prudent steps, when you begin distribution of Opaque 
copies in quantity, to ensure that this Transparent copy will remain thus accessible at the 
stated location until at least one year after the last time you distribute an Opaque copy 
(directly or through your agents or retailers) of that edition to the public. 

It is requested, but not required, that you contact the authors of the Document well before 
redistributing any large number of copies, to give them a chance to provide you with an 
updated version of the Document. 

4. MODIFICATIONS 

You may copy and distribute a Modified Version of the Document under the conditions 
of sections 2 and 3 above, provided that you release the Modified Version under precisely 
this License, with the Modified Version filling the role of the Document, thus licensing 
distribution and modification of the Modified Version to whoever possesses a copy of it. In 
addition, you must do these things in the Modified Version: 

A. Use in the Title Page (and on the covers, if any) a title distinct from that of the 
Document, and from those of previous versions (which should, if there were any, be 
listed in the History section of the Document). You may use the same title as a previous 
version if the original publisher of that version gives permission. 

B. List on the Title Page, as authors, one or more persons or entities responsible for 
authorship of the modifications in the Modified Version, together with at least five of 
the principal authors of the Document (all of its principal authors, if it has fewer than 
five), unless they release you from this requirement. 

C. State on the Title page the name of the publisher of the Modified Version, as the 
publisher. 

D. Preserve all the copyright notices of the Document. 

E. Add an appropriate copyright notice for your modifications adjacent to the other copy¬ 
right notices. 

F. Include, immediately after the copyright notices, a license notice giving the public 
permission to use the Modified Version under the terms of this License, in the form 
shown in the Addendum below. 

G. Preserve in that license notice the full lists of Invariant Sections and required Cover 
Texts given in the Document’s license notice. 

H. Include an unaltered copy of this License. 

I. Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating 
at least the title, year, new authors, and publisher of the Modified Version as given 
on the Title Page. If there is no section Entitled “History” in the Document, create 
one stating the title, year, authors, and publisher of the Document as given on its 
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Title Page, then add an item describing the Modified Version as stated in the previous 
sentence. 

J. Preserve the network location, if any, given in the Document for public access to a 
Transparent copy of the Document, and likewise the network locations given in the 
Document for previous versions it was based on. These may be placed in the “History” 
section. You may omit a network location for a work that was published at least four 
years before the Document itself, or if the original publisher of the version it refers to 
gives permission. 

K. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title 
of the section, and preserve in the section all the substance and tone of each of the 
contributor acknowledgements and/or dedications given therein. 

L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their 
titles. Section numbers or the equivalent are not considered part of the section titles. 

M. Delete any section Entitled “Endorsements”. Such a section may not be included in 
the Modified Version. 

N. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title 
with any Invariant Section. 

O. Preserve any Warranty Disclaimers. 

If the Modified Version includes new front-matter sections or appendices that qualify as 
Secondary Sections and contain no material copied from the Document, you may at your 
option designate some or all of these sections as invariant. To do this, add their titles to 
the list of Invariant Sections in the Modified Version’s license notice. These titles must be 
distinct from any other section titles. 

You may add a section Entitled “Endorsements”, provided it contains nothing but endorse¬ 
ments of your Modified Version by various parties—for example, statements of peer review 
or that the text has been approved by an organization as the authoritative definition of a 
standard. 

You may add a passage of up to five words as a Front-Cover Text, and a passage of up 
to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified 
Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added 
by (or through arrangements made by) any one entity. If the Document already includes 
a cover text for the same cover, previously added by you or by arrangement made by the 
same entity you are acting on behalf of, you may not add another; but you may replace the 
old one, on explicit permission from the previous publisher that added the old one. 

The author(s) and publisher(s) of the Document do not by this License give permission to 
use their names for publicity for or to assert or imply endorsement of any Modified Version. 

5. COMBINING DOCUMENTS 

You may combine the Document with other documents released under this License, under 
the terms defined in section 4 above for modified versions, provided that you include in the 
combination all of the Invariant Sections of all of the original documents, unmodified, and 
list them all as Invariant Sections of your combined work in its license notice, and that you 
preserve all their Warranty Disclaimers. 

The combined work need only contain one copy of this License, and multiple identical 
Invariant Sections may be replaced with a single copy. If there are multiple Invariant 
Sections with the same name but different contents, make the title of each such section 
unique by adding at the end of it, in parentheses, the name of the original author or 
publisher of that section if known, or else a unique number. Make the same adjustment to 
the section titles in the list of Invariant Sections in the license notice of the combined work. 
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In the combination, you must combine any sections Entitled “History” in the various original 
documents, forming one section Entitled “History”; likewise combine any sections Entitled 
“Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections 
Entitled “Endorsements.” 

6. COLLECTIONS OF DOCUMENTS 

You may make a collection consisting of the Document and other documents released under 
this License, and replace the individual copies of this License in the various documents with 
a single copy that is included in the collection, provided that you follow the rules of this 
License for verbatim copying of each of the documents in all other respects. 

You may extract a single document from such a collection, and distribute it individually 
under this License, provided you insert a copy of this License into the extracted document, 
and follow this License in all other respects regarding verbatim copying of that document. 

7. AGGREGATION WITH INDEPENDENT WORKS 

A compilation of the Document or its derivatives with other separate and independent 
documents or works, in or on a volume of a storage or distribution medium, is called an 
“aggregate” if the copyright resulting from the compilation is not used to limit the legal 
rights of the compilation’s users beyond what the individual works permit. When the 
Document is included in an aggregate, this License does not apply to the other works in 
the aggregate which are not themselves derivative works of the Document. 

If the Cover Text requirement of section 3 is applicable to these copies of the Document, 
then if the Document is less than one half of the entire aggregate, the Document’s Cover 
Texts may be placed on covers that bracket the Document within the aggregate, or the 
electronic equivalent of covers if the Document is in electronic form. Otherwise they must 
appear on printed covers that bracket the whole aggregate. 

8. TRANSLATION 

Translation is considered a kind of modification, so you may distribute translations of the 
Document under the terms of section 4. Replacing Invariant Sections with translations 
requires special permission from their copyright holders, but you may include translations 
of some or all Invariant Sections in addition to the original versions of these Invariant 
Sections. You may include a translation of this License, and all the license notices in 
the Document, and any Warranty Disclaimers, provided that you also include the original 
English version of this License and the original versions of those notices and disclaimers. In 
case of a disagreement between the translation and the original version of this License or a 
notice or disclaimer, the original version will prevail. 

If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, 
the requirement (section 4) to Preserve its Title (section 1) will typically require changing 
the actual title. 

9. TERMINATION 

You may not copy, modify, sublicense, or distribute the Document except as expressly pro¬ 
vided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute 
it is void, and will automatically terminate your rights under this License. 

However, if you cease all violation of this License, then your license from a particular copy¬ 
right holder is reinstated (a) provisionally, unless and until the copyright holder explicitly 
and finally terminates your license, and (b) permanently, if the copyright holder fails to 
notify you of the violation by some reasonable means prior to 60 days after the cessation. 
Moreover, your license from a particular copyright holder is reinstated permanently if the 
copyright holder notifies you of the violation by some reasonable means, this is the first 
time you have received notice of violation of this License (for any work) from that copyright 
holder, and you cure the violation prior to 30 days after your receipt of the notice. 
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Termination of your rights under this section does not terminate the licenses of parties 
who have received copies or rights from you under this License. If your rights have been 
terminated and not permanently reinstated, receipt of a copy of some or all of the same 
material does not give you any rights to use it. 

10. FUTURE REVISIONS OF THIS LICENSE 

The Free Software Foundation may publish new, revised versions of the GNU Free Doc¬ 
umentation License from time to time. Such new versions will be similar in spirit to the 
present version, but may differ in detail to address new problems or concerns. See http:// 
www.gnu. org/copyleft/. 

Each version of the License is given a distinguishing version number. If the Document 
specifies that a particular numbered version of this License “or any later version” applies 
to it, you have the option of following the terms and conditions either of that specified 
version or of any later version that has been published (not as a draft) by the Free Software 
Foundation. If the Document does not specify a version number of this License, you may 
choose any version ever published (not as a draft) by the Free Software Foundation. If the 
Document specifies that a proxy can decide which future versions of this License can be 
used, that proxy’s public statement of acceptance of a version permanently authorizes you 
to choose that version for the Document. 

11. RELICENSING 

“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web 
server that publishes copyrightable works and also provides prominent facilities for anybody 
to edit those works. A public wiki that anybody can edit is an example of such a server. A 
“Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of 
copyrightable works thus published on the MMC site. 

“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published 
by Creative Commons Corporation, a not-for-profit corporation with a principal place of 
business in San Francisco, California, as well as future copyleft versions of that license 
published by that same organization. 

“Incorporate” means to publish or republish a Document, in whole or in part, as part of 
another Document. 

An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that 
were first published under this License somewhere other than this MMC, and subsequently 
incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, 
and (2) were thus incorporated prior to November 1, 2008. 

The operator of an MMC Site may republish an MMC contained in the site under CC-BY- 
SA on the same site at any time before August 1, 2009, provided the MMC is eligible for 
relicensing. 
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ADDENDUM: How to use this License for your documents 

To use this License in a document you have written, include a copy of the License in the document 
and put the following copyright and license notices just after the title page: 

Copyright (C) year your name. 

Permission is granted to copy, distribute and/or modify this document 
under the terms of the GNU Free Documentation License, Version 1.3 
or any later version published by the Free Software Foundation; 
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 
Texts. A copy of the license is included in the section entitled ''GNU 
Free Documentation License 11 . 

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the 
“with. . .Texts.” line with this: 

with the Invariant Sections being list their titles, with 
the Front-Cover Texts being list, and with the Back-Cover Texts 
being list. 

If you have Invariant Sections without Cover Texts, or some other combination of the three, 
merge those two alternatives to suit the situation. 

If your document contains nontrivial examples of program code, we recommend releasing 
these examples in parallel under your choice of free software license, such as the GNU General 
Public License, to permit their use in free software. 
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\absolute. 39 

\acciaccatura. 26 

\addlyrics. 31 

\addlyrics example. 91 

\addlyrics, example. 95 

\appoggiatura. 26 

\autoBeamOff. 25, 55 

\autoBeamOn. 25 

\book. 40, 41 

\clef. 16 

\consists. 66 

\context. 65 

\f. 24 

\ff. 24 

\grace. 26 

\header. 37, 41 

\hide. 99 

\key. 21 

\layout. 41, 67 

Myricmode. 55 

Myricsto. 55 

\major. 21 

\markup. 24 

\mf. 24 

\midi. 41 

\minor. 21 

\mp. 24 

\new. 28, 59 

\new ChoirStaff. 55 

\new Lyrics. 55 

\new Staff. 28 

\new Voice. 51 

\omit. 98, 102 

\once. 88, 93 

\oneVoice. 51 

\override. 87 

\overrideProperty. 89 

\p. 24 

\partial. 25 

\pp. 24 

\relative. 12 

\remove. 66 

\revert. 88, 94 

\score. 40, 42 

\set. 61 

\set, example of using. 110 

\shift0ff. 54, 122 

\shift0n. 54, 122 

\shift0nn. 54, 122 

\shift0nnn. 54, 122 

\single. 136 

\startTextSpan. 112 

\stopTextSpan. 112 

\tempo. 15 

XtextLengthOff . 114 

XtextLengthOn. 114 

\time. 15 

\tuplet. 26 
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\tweak. 89 

\tweak, Accidental. 90 

\tweak, example. 89, 90 

\tweak, specific layout object. 90 

\unset. 61 

\version. 16 

\voiceFour. 51 

\voiceFourStyle. 49 

\voiceNeutralStyle. 49 

\voice0ne. 51 

\voiceOneStyle . 49 

\voiceThree. 51 

\voiceThreeStyle. 49 

\voiceTwo. 51 

\voiceTwoStyle . 49 

\with. 64 

\with, example. 102, 103, 105, 106 


22 


A 

absolute mode. 37 

absolute note names. 37 

absolute values for pitches. 37 

accent. 23 

acciaccatura. 26 

Accidental, example of overriding. 124 

AccidentalPlacement, example of overriding. 124 

accidentals. 20 

accidentals and key signature. 21 

accidentals and key signatures. 20 

accidentals and relative mode. 12 

adding engravers. 66 

adding text. 24 

addlyrics. 31 

adjustments, using variables for. 138 

alignAboveContext property, example. 102, 103, 

105, 106 

aligning lyrics. 31 

aligning objects on a baseline. 124 

alto. 16 

ambitus engraver. 66 

anacrusis. 25 

appoggiatura. 26 

articulation. 23 

articulations and slurs. 113 

assigning variables. 36 

autoBeamOff. 25, 55 

autoBeamOn. 25 

automatic beams. 25 


B 

bar numbers, tweaking placement. 112 

BarLine, example of overriding .. 97, 98, 99, 100, 101 

bass. 16 

Beam, example of overriding. 127 

beaming. 25 

beaming and lyrics. 55 

beams, automatic. 25 

beams, by hand. 25 

beams, controlling manually. 126 


beams, manual. 25 

block comment. 16, 17 

book. 40, 41 

book block, implicit. 41 

bound-details property, example. 112 

braces, curly. 16 

bracket types. 45 

bracket, triplet. 90 

bracket, tuplet. 90 

brackets, enclosing vs. marking. 45 

brackets, nesting. 45 

break-visibility property. 99 

break-visibility property, example. 99 


case sensitive. 1, 16 

center. 108 

changing size of objects. 102 

characters allowed in variables. 36 

choir staff. 29, 55 

ChoirStaff. 29, 55 

ChordNames. 28 

chords. 30 

chords vs. voices. 47 

clef. 16 

Clef, example of overriding... 101, 102, 103, 105, 106 

clickable examples. 18 

collisions, notes. 54, 122 

color property. 100 

color property, example. 88, 90, 100, 101 

color property, setting to Scheme procedure. 145 

color, rgb. 101 

color, Xll. 101 

combining expressions in parallel. 27 

comma. 12 

comment, line. 16 

comments. 16, 17 

common errors. 18 

compiling. 1 

compound music expression. 26, 42 

concurrent music. 47 

consists. 66 

constructing files, tips. 18 

content vs. layout. 21 

contents of a score block. 42 

context. 28 

context. 65 

context properties. 61 

context properties, modifying. 61 

context properties, setting with \context. 65 

context properties, setting with \with. 64 

context, finding. 93 

context, identifying correct. 93 

context, notation. 28 

context, Voice. 47 

contexts explained. 58 

contexts, creating. 59 

contexts, implicit. 40 

contexts, naming. 60 

controlling tuplets, slurs, phrasing slurs, and beams 

manually. 126 

creating contexts. 59 

crescendo. 24 
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curly braces. 

D 

decrescendo. 

default properties, reverting to. 

direction property, example. 90, 108, 

distances. 

dotted note. 

double flat. 

double sharp. 

down. 

durations. 

DynamicLineSpanner, example of overriding. 

dynamics. 

dynamics, tweaking placement. 

DynamicText, example of overriding. 116, 

E 

engravers. 

engravers, adding. 

engravers, removing. 

errors, common. 

es. 

eses. 

example of writing a score. 

example, first. 

examples, clickable. 

expression, music. 

expressions. 

expressions, parallel. 

extender line. 

extra-offset property. 

extra-offset property, example. 

extra-spacing-width. 

extra-spacing-width property. 

extra-spacing-width property, example. 116, 

F 

fermata, implementing in MIDI. 

file structure. 

files, tips for constructing. 

fingering. 

fingering example. 109, 

fingering, chords. 

Fingering, example of overriding. 109, 

fingering, placement. 

fingeringOrientations property, example. 


first example. 

fixing overlapping notation. 

flat. 

flat, double. 

font-series property, example. 

font-shape property, example. 95, 

font-size property, example. 

fontSize property, example. 105, 

fontSize, default and setting. 

force-hshift property. 

force-hshift property, example. 128, 


G 

grace. 26 

grace notes. 26 

grand staff. 29 

GrandStaff. 29 

graphical objects. 79 

grob. 86 

grob sizing. 115 

grobs. 79 

grobs, moving colliding. 120 

grobs, positioning. 125 

grobs, properties of. 91 

H 

half note. 14 

header. 37, 41 

header block. 37 

headers. 37 

hiding objects. 136 

horizontal-shift property. 122 

how to read the manual. 18 

hymn structure. 56 

hyphens. 31 

I 

identifiers. 36 

implicit book block. 41 

implicit contexts. 40 

input format. 40 

interface. 86, 95 

interface properties. 95 

Internals Reference. 91 

Internals Reference manual. 91 

Internals Reference, example of using. 91 

invisible objects. 136 

is. 20 

isis. 20 

italic, example. 95 

K 

key. 21 

key signature. 21 

key signature, setting. 21 

L 

layers. 47 

layout. 41, 67 

layout adjustments, using variables for. 138 

layout block, effect of location. 41 

layout object. 86 

layout objects, properties of. 91 

layout vs. content. 21 

length. 105 

line comment. 16, 17 

lyricmode. 55 

lyrics. 31 

Lyrics. 28, 55 

lyrics and beaming. 55 

lyrics and multiple staves. 35 

Lyrics context, creating. 55 
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lyrics, aligning. 31 

lyrics, linking to voice. 55 

lyrics, multi-syllable words. 31 

lyricsto. 55 

LyricText, example of overriding. 95, 138 


M 

MacOS X, running LilyPond. 2 

macros. 36 

magstep. 105 

magstep function, example of using. 106 

major. 21 

manual beams. 25 

manual, reading. 18 

manually controlling tuplets, slurs, phrasing slurs, 

and beams. 126 

Manuals. 1 

markup. 24 

markup example. 107 

markup text, allowing collisions. 114 

melisma. 31 

metronome mark, tweaking placement. 112 

metronome marks. 15 

MetronomeMark, example of overriding. 123, 137 

midi. 41 

minor. 21 

modifying context properties. 61 

modifying templates. 69 

moving colliding grobs. 120 

moving colliding objects. 120 

moving overlapping objects. 120 

MultiMeasureRest, example of overriding. 125 

multiple staves. 27, 28 

multiple staves and lyrics. 35 

multiple vocal verses. 56 

multiple voices. 30, 47 

music expression. 26 

music expression, compound. 26, 42 

music, concurrent. 47 

music, simultaneous. 47 


N 

naming contexts. 60 

naming conventions for objects. 87 

naming conventions for properties. 87 

nesting music expressions. 53 

nesting simultaneous constructs. 53 

nesting voices. 53 

neutral. 108 

new. 28, 59 

new contexts. 59 

new Staff. 28 

notating durations. 14 

notating rests. 15 

notation context. 28 

notation, simple. 12 

note collisions. 54, 122 

note column. 54, 122 

note durations. 14 

note durations in chords. 30 

note names. 37 

note names, absolute. 37 


NoteColumn, example of overriding. 128, 134 

NoteHead, example of overriding .... 88, 89, 101, 145 
notes, spreading out with text. 114 


o 

object. 86 

object collision within a staff. 125 

object properties. 86 

object, layout. 86 

objects, aligning on a baseline. 124 

objects, changing size of. 102 

objects, graphical. 79 

objects, hiding. 136 

objects, invisible. 136 

objects, making invisible. 136 

objects, moving colliding. 120 

objects, naming conventions. 87 

objects, outside-staff. 106 

objects, positioning. 125 

objects, removing. 136 

objects, size of. 102 

objects, within-staff. 106 

once. 88, 93 

once override. 93 

oneVoice. 51 

ossias. 44 

ottava bracket. 112 

outside-staff objects. 106 

outside-staff-priority property, example. 113, 114 

overlapping notation. 123 

override. 87 

override command. 87 

override example. 91 

override syntax. 87 

overrideProperty. 89 

overrideProperty command. 89 

overrides, using variables for. 138 

overriding once only. 93 


P 

padding. 121, 123 

padding property. 121 

padding property, example. 123 

parallel expressions. 27 

parallel expressions and relative notes. 27 

partial. 25 

partial measure. 25 

PDF file. 1 

phrasing slur. 22 

phrasing slurs, controlling manually. 126 

PlirasingSlur, example of overriding. 126 

piano staff. 29 

PianoStaff. 29 

pickup. 25 

pitches. 12 

pitches, absolute values. 37 

polyphony. 27, 30, 47 

polyphony and relative note entry. 49 

positioning grobs. 125 

positioning objects. 125 

positions property. 123 

positions property, example. 126, 127 




















































































































Appendix C: LilyPond index 


196 


properties in interfaces. 95 

properties of grobs. 91 

properties of layout objects. 91 

properties operating in contexts. 62 

properties, naming conventions. 87 

properties, object. 86 

properties, sub-properties. 79 

property types. 96 


Q 

quarter note. 14 



reading the manual. 18 

rehearsal marks, tweaking placement. 112 

relative. 12 

relative mode. 12 

relative mode, and accidentals. 12 

relative note entry and polyphony. 49 

relative notes and parallel expressions. 27 

relative notes and simultaneous music. 27 

remove. 66 

removing engravers. 66 

removing objects. 136 

rest. 15 

rest, spacer. 30 

revert. 88, 94 

revert command. 88 

reverting to a single voice. 52 

rgb colors. 101 

rgb-color. 101 

rhythms. 14 

right-padding property. 121, 124 

right-padding property, example. 124 

running LilyPond under MacOS X. 2 

running LilyPond under Unix. 11 

running LilyPond under Windows. 6 


s 

SATB structure. 56 

SATB template. 72 

score. 40, 42 

Score. 28 

score block, contents of. 42 

score, example of writing. 77 

scores, multiple. 41 

Script, example of overriding. 123 

self-alignment-X property. 121 

self-alignment-X property, example. 125 

set. 61 

setting properties within contexts. 62 

sharp. 20 

sharp, double. 20 

shift commands. 54, 122 

shiftOff. 54, 122 

shiftOn. 54, 122 

shiftOnn. 54, 122 

shiftOnnn. 54, 122 

simple notation. 12 

simultaneous music. 47 


simultaneous music and relative notes. 27 

single staff polyphony. 30 

size of objects. 102 

size, changing. 105 

sizing grobs. 115 

slur. 22 

Slur example of overriding. 92 

Slur, example of overriding. 93, 94 

slur, phrasing. 22 

slurs and articulations. 113 

slurs and outside-staff-priority. 113 

slurs crossing brackets. 48 

slurs versus ties. 23 

slurs, controlling manually. 126 

songs. 31 

spacer rest. 30 

spacing notes. 54 

spanner. 86 

spanners. Ill 

staccato. 23 

Staff. 28 

staff group. 29 

staff line spacing, changing. 105 

staff, choir. 29 

staff, grand. 29 

staff, piano. 29 

staff, positioning. 45 

staff-padding property. 121 

staff-padding property, example. 124 

staff-position property. 122 

staff-position property, example. 125, 133 

staff-space property, example. 106 

StaffSymbol, example of overriding. 101, 106 

startTextSpan. 112 

staves, multiple. 27, 28 

staves, stretchability. 79 

staves, temporary. 44 

stem directions and voices. 51 

stem down. 51 

stem length, changing. 105 

stem up. 51 

Stem, example of overriding. 101, 108, 134, 136 

stencil property. 97 

stencil property, example .. 97, 98, 100, 106, 124, 137 

stencil property, use of. 137 

stopTextSpan. 112 

stretchability of staves. 79 

StringNumber, example of overriding. 125 

sub-properties. 79 


T 

template, modifying. 69 

template, SATB. 72 

template, writing your own. 77 

templates. 18 

tempo. 15 

tempo marks. 15 

temporary staves. 44 

tenor. 16 

text editors. 1 

text property, example. 91, 124 

text spanner. 112 

text, adding. 24 
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textLengthOf f. 114 

textLengthOn. 114 

TextScript, example of overriding. 113, 114 

TextSpanner, example of overriding. 112 

thickness. 105 

thickness property, example. 92, 93, 94 

tie. 22 

Tie, example of overriding. 133 

ties crossing brackets. 48 

time. 15 

time signature. 15 

TimeSignature, example of overriding .. 99, 100, 101, 
102, 103, 105, 106 

tips for constructing files. 18 

title. 37 

transparency. 99 

transparent property. 99 

transparent property, example.. 91, 99, 134, 136, 137 

transparent property, use of. 136 

treble. 16 

triplet bracket. 90 

triplets. 26 

triplets, nested. 90 

troubleshooting. 18 

tuplet. 26 

tuplet beams, controlling manually. 126 

tuplet bracket. 90 

tuplet-number function, example. 91 

TupletBracket. 90 

TupletNumber, example of overriding. 91 

tuplets. 26 

tuplets, nested. 90 

tweak. 89 

tweak command. 89 

tweak, generated from override. 136 

tweaking bar number placement. 112 

tweaking dynamics placement. 115 

tweaking methods. 87 

tweaking metronome mark placement. 112 

tweaking rehearsal mark placement. 112 

tying notes across voices. 136 


u 

underscore. 31 

Unix, running LilyPond. 11 

unset. 61 

up. 108 

using variables. 36 


V 

variables. 36, 41, 82 

variables, characters allowed in. 36 

variables, defining. 36 

variables, using. 36 

variables, using for overrides. 138 

verses, multiple vocal. 56 

version. 16 

version number. 16 

versioning. 16 

viewing music. 1 

vocal score structure. 55 

vocal scores with multiple verses. 56 

Voice. 28 

Voice context. 47 

voice contexts, creating. 51 

voiceFour. 51 

voiceOne. 51 

voices and stem directions. 51 

voices crossing brackets. 48 

voices vs. chords. 47 

voices, more on one staff. 30 

voices, multiple. 47 

voices, naming. 48 

voices, nesting. 53 

voices, reverting to single. 52 

voices, temporary. 53 

voiceThree. 51 

voiceTwo. 51 


w 


whitespace insensitive. 16 

whole note. 14 

Windows, running LilyPond. 6 

with. 64 

within-staff objects. 106 

words with multiple syllables in lyrics. 31 

writing a score, example. 77 

X 

XI1 colors. 101 

xll-color. 101 

xl 1-color function, example of using. 145 

xll-color, example of using. 101 




















































































